Contributor Handbook

Reference: Github's Collaborative Development Models

RoQ adopts both of the Collaborative Development Models available on Github. New contributors will use the Fork + Pull Model while the core developers will have direct access to the main repository and use the Shared Repository Model.

1.1 New Contributors

As specified above, new external contributors can start their venture into contributing to RoQ using the Fork + Pull Model. The process is described hereafter (a more detailed version can be found on the aforementioned github help page).

1.1.1 For the contributor

1. Fork the RoQ repository ("fork" on https://github.com/roq-messaging/RoQ )
2. Work on your features on a branch of your own repository
3. Trigger a "pull request" from your repository page.
4. Review the included commits and their diffs
5. Wait for approval

1.1.2 For the main repository's admin

1. Review the proposed changes in the pull request submitted
2. Discuss it with the contributor if necessary
3. Merge the request (github automerge if possible, or using git-am or fetch&merge)
4. Close the pull request

1.2 Core Developers

Developers which are familiar both with git and with RoQ will be granted write access to RoQ repository. They will follow the Shared Repository Model to work together.

1.2.1 The branching model

• shared branches
  • master: used for releases. Nobody should ever commit to master except the release manager.
  • develop: main development branch. This is where the "nightly" code is found. This is the branch which is used by the CI tooling to test&build.
  • release and hotfix branches: forked to prepare a release or a hotfix
• local branches
  • feature branch: forked from develop, merged to develop. Used to work locally on a feature. If the feature is big, this branch can sometimes be non-local. In that case, you should prefix its name with "develop-" and use it as you would use "develop".

The usual best practice is to always commit on a branch that is local in order to be certain that you will not generate any conflict later on.

1.2.2 RoQ best practices

• never commit or merge with master
• always merge and never commit on remote (shared) branches (e.g. master, develop)
• before merging your local branch into a shared branch, always:
  • pull to make sure the shared branch is up to date
  • rebase your local branch using the shared branch
  • merge

1.2.3 Cloning the repository

Please make sure your public key has been added to the roq-messaging account.

git clone git@github.com:roq-messaging/RoQ.git

1.2.4 Working on a feature

First, create a feature branch

git checkout develop
git checkout -b my-new-feature

Then, work on your feature. When you're done, merge with develop:

git checkout develop 
git pull origin develop
git rebase develop my-new-feature
git checkout develop
git merge --no-ff my-new-feature -m "describe the feature"
git push origin develop

Note: frequent rebasing is recommended in order to make sure you integrate as soon as possible changes coming from other contributors.