How to contribute to Brainstorm using GitHub

Authors: Martin Cousineau

Since Brainstorm is an open-source application, the whole codebase is available for free on GitHub, a website that facilitates version control and collaboration between developers. This means everyone is able and encouraged to submit improvements and new features of the software themselves through the GitHub interface.

GitHub runs on top of the popular version control software Git. This webpage presents a very simple introduction to using Git and submit code modifications on GitHub. Be aware that Git is a very widely used and powerful tool, therefore this page does not replace a proper documentation or tutorial. The purpose is simply to get beginners started, with the example using the Brainstorm codebase.

Basic Concepts

We will first introduce some basic concepts and keywords that you will see often when working with Git. They will be introduced in descending order of complexity, as in for example house -> room -> furniture.

Repository: A repository (often shortened to repo) is essentially the full codebase of a software, with all its past versions saved, as well as any active modifications that were saved but not yet merged in the latest published version of the software.

Fork: A fork is a copy of a specific repository, belonging to a certain user. This is required to make a change to a repository when you're not its owner. You will need to fork the repository of interest, make the change on your own fork, then submit the change to the owners of the repository for review. When you look at a GitHub URL, you identify right away the fork owner and the repository name. For example, in the URL https://github.com/martcous/brainstorm3, the owner is user Martcous and the repository is Brainstorm3.

Branch: A branch is essentially a pointer towards the last modification of a software relevant to a specific feature. Every repository has a master branch, which is the latest stable version of the software available to users. Then, a repository will have one or multiple custom branches with a certain name chosen by the developer where the changes relevant to a certain feature. For example, if you're working on an improvement to the filtering process of Brainstorm, you might create a branch called "filter_improvements", make some changes saved in that custom branch, and when you're ready ask for it to be merged in the master branch by the owner.

Pull Request: A pull request (often abbreviated to PR) is a request sent to the repository's owner to merge your custom branch into the master branch. This is created when you consider your changes in your custom branch to be final and ready for public use. The owner will then have a possibility to review your changes, make comments and suggestions, and finally merge your changes into the master branch (and therefore the latest public version of the software). Pull requests are commonly refered by their automatically generated IDs (e.g. PR #120).

Commit: A commit is a set of code changes grouped together. It can span one or multiple files of the same codebase.