Skip to content

How to contribute to this project

Jump to bottom
Matteo Bunino edited this page Oct 2, 2023 · 7 revisions

DevOps guidelines

This quick guide describes the guidelines to follow when contributing to this repository. See also: Collaborative DevOps notes.

Development is done on the dev branch. On the completion of each milestone, once the code is stable, the dev branch is merged into the main branch.

New feature or bug fix:

  1. Create new GH issue
  2. Create new branch related to that issue, branching out from dev, NOT main.
  3. Commit changes to branch
  4. Open a pull request to merge the changes into dev branch.

Test-driven development: write tests before you write the application code.

  1. Write the test function.
  2. Run the test function - which should fail.
  3. Write the feature that is intended for the test.
  4. Run the test again. If the test passes, move on to the next test. Merge dev branch into main branch once all unit and integration tests pass.

Collaborative development

During collaborative development, you need be in sync with the others:

  • Push your changes so that the other are aware of your changes.
  • Pull changes to be up-to-date with the recent changes, making sure you are not working on an outdated version of the codebase.

Goal: do not diverge from other people's work.

How often to merge into the dev branch

A change to the dev branch is described in the associated GH issue. The granularity of a change is a critical parameter: breaking a problem into too small changes and merging to dev too often is an overhead, whereas too many changes at the same time delay the update of the dev branch.

Delayed updates to the dev branch are bad: risk of diverging from the work of the others. Remember to merge into dev branch frequently. Thus, the granularity of the problem you are solving should be adequate.

Sync with the latest changes in the dev branch

When working on a new issue, you will branch out from dev and commit some changes in some feature branch, resulting in a situation like this:

06 Developing a feature in a dedicated branch

In parallel, your colleagues are working on their private branches, regularly merging their changes into dev, once stable enough. Your code will become outdated with respect to the latest version on dev:

01 A forked commit history

You need to bring the new changes into your branch to make sure your work does not diverge from is on dev: time to rebase your branch on top of dev:

git checkout your-branch-name
git rebase dev

03 Rebasing the feature branch into main

The rebase command will replay all the commits on your branch as if they were executed on the current "head" of the dev branch. Rebasing is of critical importance if you are collaboratively developing the same feature, thus you need to be always in sync with the updates on the feature.

Reference and picture credits to Atlassian's Git guide.

Clone this wiki locally