Onboarding Doc (draft)

Feb 17, 2020

We have recently updated our onboarding doc for developers as we have a lot of people and orgs looking to start development on existing platforms in the Cokoverse. Below is pretty much the gist of it. If you have comments on how to improve this please email Adam! (adam@coko.foundation).


ONBOARDING GUIDE

 

Tools

The first thing you should do is sign up for the tools we use to get work done. We use 100% open source tools. If you are looking for information on contributing (including testing) please look at the contributing guide in each of the project repositories.

Gitlab

gitlab.coko.foundation
This is where the code for all our projects lives. You can find links to specific projects further down in this document. You can create your own account.

Mattermost

mattermost.coko.foundation

Where all of the community chats to each other. As a developer, you should probably subscribe to the PubSweet channel, as well as any project-specific channels that might be of interest. You can create your own account. There are also mobile and desktop apps for mattermost.

Discourse

discourse.coko.foundation

Our very own instance of discourse. If you need help with installing one of the applications or using one of libraries, you should open a ticket in discourse. This is preferred over simply asking on mattermost, as it will make it more discoverable for people that experience similar difficulties in the future. You can create your own account. There are mobile apps for discourse.

Jitsi

meet.jit.si/

We use Jitsi for all calls. It is a browser based video conferencing app. It doesn’t need an account. Jitsi also has mobile apps.

Infrastructure support

https://support.cloud68.co/

Collective 68 is the organisation that takes care of our internal systems infrastructure. If you experience technical issues with one of the tools above (e.g. gitlab server is down), please open a ticket there for a quick response.

Our technology stack

Our projects use the following technologies.

Postgres

All of our projects use Postgres as a database (it is also a requirement for PubSweet). You should be able to work with it or another SQL-based relational database.

Documentation:
https://www.postgresql.org/docs/

Node / Express

Our server code is based on node and more specifically on the lightweight express.js framework.

Documentation:
https://nodejs.org/en/docs/
https://expressjs.com/en/4x/api.html

Graphql / Apollo

All of our applications have a GraphQL API, and we use apollo to make that happen.

Documentation:
https://www.apollographql.com/docs/

React & Styled components

You are very likely to be working on UI components. We use react, as well as styled components for CSS styles. It is expected that you are well versed in both of these libraries.

Documentation:
https://reactjs.org/docs/getting-started.html
https://styled-components.com/docs

Working locally

We strongly recommend that you have a development environment that has support for modern features (e.g. linting). You are free to use whatever you want, but most of us use Visual Studio Code and its extensions without any issues.

It is expected that the applications will be run on a *nix operating system.

That means that in order for things to work locally for you, you should be working on a Linux distribution (e.g. Ubuntu, Manjaro, etc.), MacOS or, if on Windows, inside the Windows Subsystem for Linux (WSL2 — the “2” is important here).

It is also expected that you have the following technologies installed locally:

Git

We don’t require people to be git experts, but working knowledge of git branching, committing, merging and rebasing is expected.

Documentation:
https://git-scm.com/book/en/v2

(if you read up to chapter 3, you should be good to start working)

Docker & docker-compose

Most of our projects use docker in one form or another. Familiarity with running simple docker and docker-compose commands is expected.

Documentation:
https://docs.docker.com/
https://docs.docker.com/compose/

Built with Pubsweet

PubSweet is a Coko-built Javascript framework that all the apps in our ecosystem are builton. So, before you jump into one of the projects, be sure to do some reading on what PubSweet is and what it provides first.

Documentation:
https://pubsweet.coko.foundation/

Code:
https://gitlab.coko.foundation/pubsweet/pubsweet

Getting Started

As a developer, before working with the projects we recommend you first do the following:

  • create accounts on mattermost, discourse and gitlab at the very least
  • read the PubSweet documentation
  • set up your dev environment
  • install PubSweet
  • install Editoria or one of the other applications

After the above we will include you in a onboarding training schedule.

If you have any issues when installing PubSweet/Editoria (etc.) please file them in the discourse instance. We want as much help discussion as possible to happen through discourse.