Onboarding Doc (draft)
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
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
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
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.