If you want to create your own or contribute to an existing GitHub project, you are on the right page.

Contribution scenarios

You can contribute to a GitHub project in several ways: reporting bugs, submitting fixes, proposing new features, or becoming a maintainer.

Main principles

Here is the main contribution workflow:

GitHub contribution workflow diagram

Steps for contribution

0. Prerequisites

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

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

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

Replace "ProjectName" with 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:

bash
# If the default branch is "main"
git pull upstream main
Note

If the project repository uses a different default branch name than "main", substitute it accordingly.

2. Create a new branch

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

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

bash
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:

bash
git branch

You should see your new branch as well as "main", with an asterisk next to the branch that's currently checked out.

3. Make changes in your local repository

Open a text editor or IDE such as Visual Studio Code to implement the changes you have planned. Since you checked out a branch in the previous step, any modifications you make will be confined to that branch.

4. Commit your changes

After you make a set of changes, stage them:

bash
git add .

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

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

This commit message might be included in a changelog. Commit messages should follow Conventional Commits , e.g. feat:, release:, hotfix:, fix:.

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 them to your branch:

bash
git push origin my_new_feature

This command pushes your changes to the my_new_feature branch of your fork on GitHub.

6. Create a pull request

A pull request is created when a developer asks for changes committed to a specific branch to be considered for inclusion in another branch of the repository.

Go to your GitHub project's web page, open the Pull requests menu, and click New pull request, then Create pull request.

If there are no conflicts between your fork and the main branch, your pull request will be created and contributors will be notified. They will then review your changes and choose to merge your code or not.

Add colleagues working on the repository as reviewers and yourself as an assignee — reviewers will be notified by email automatically. As a best practice, let your colleagues know about your pull request through a direct message, as GitHub emails are frequently ignored.

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.

Code review process

8. Merge to the main branch

Congratulations! Your code has been successfully reviewed and merged into the main branch. It is now available for others to build upon.

Golden rules