Skip to main content

Contributing workflow

Contributing workflow​

Make contributions on various topics:

  • Report a bug
  • Submit a fix
  • Propose new features
  • Become a maintainer
  • ...

Main principles​

  • The main branch is locked, no direct commit possible.
  • Each developer work in their own branch from main
  • Developer do a pull request
  • Once PR is validated, the code is merged
  • A release is created

Here is the main contribution workflow:

Image

Steps for contribution​

1. Pull the latest changes from upstream into your local repository​

To start working on your contribution, you need first to retrieve the project on your local repository.

To do so, use this command  :

git clone https://github.com/Benoit-Gaumard/ProjectName
tip

"ProjectName" by the actual project you want to contribute to.

Before you start making any changes to your local files, it's a good practice to first synchronize your local repository with the project repository.

 Use the following command to "pull" any changes from the "master" branch of the "upstream" into your local repository.

git pull upstream master
tip

If the project repository uses "main" instead of "master" for its default branch, then you would use git pull upstream main instead.

2. Create a new branch​

Rather than making changes to the project's "master" branch, it's a good practice to instead create your own branch. This creates an environment for your work that is isolated from the master branch.

Use this command to create a new branch and then immediately switch to it. The name of the branch should briefly describe what you are working on, and should not contain any spaces.

git checkout -b my_new_feature

For example, I used git checkout -b doc-fixes because I was making some small fixes to the documentation.

To show your local branches, use this command :

git branch

You should see your new branch as well as "master", and your new branch should have an asterisk next to it to indicate that it's "checked out" (meaning that you're working in it).

3. Make changes in your local repository​

Use a text editor or IDE like Microsoft VS Code to make the changes you planned to the files in your local repository. Because you checked out a branch in the previous step, any edits you make will only affect that branch.

Download VS Code here: Visual Studio Code

4. Commit your changes​

After you make a set of changes, use the following command to stage your changes.

git branch

The description of your commit must be clear, explicit and understandable to anyone, example :

git commit -m "fix: typos in set_config docstring"

This commit message might be included in a changelog.

Commit messages must be standardized: Conventional Commits

If you are making multiple sets of changes, it's a good practice to make a commit after each set.

5. Push changes to your branch​

When you are done making all of your changes, upload these changes to your branch using :

git push origin my_new_feature

This command "pushes" your changes to the "my_new_feature" branch of the "origin" (which is your fork on GitHub).

6. Create a pull request​

Go to your Github project web page in the Pull request menu and click on New pull request.

Once it's done, click on Create pull request.

If there is no conflicts between your fork and the main branch, your pull request will be created and contributors will be notify. The contributors will then analyse your fork and choose to merge your code or not.

7. Code Review​

Before merging, the code should be reviewed by peers, code review involves one or more team members checking another teammate's work.

8. Merge to the main branch​

Congratulations! Your code has been reviewed and merged into the main branch. It can be reused by someone to make a new contribution.