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. A branch is therefore simply a set of commits applied one after the other. Once a commit is applied to a new branch, it will have diverged from its original branch (typically master). Once the repository owner approves your pull request, they will merge the custom branch into the master branch, which applies all new commits to the master. A specific commit is typically refered by its hash or shortened to the first 7 characters of its hash (e.g. this is commit 96f44a9or 96f44a9b7fbafc875af3d42c4a1db046b0574153), which is the last part of the GitHub URL of the commit.

Still with me? Don't worry, with practice these concepts will sink in easily. Just refer to this section whenever you forget what a term means.

Setup

The following section will describe a one time setup for your GitHub account and computer.

GitHub Account

The first very obvious thing for you to do will be to create your own GitHub account. You can follow the instructions on the following page: https://github.com/join. When asked, make sure to choose a free plan. You do not require any of the paid features to contribute to Brainstorm.

Fork the Brainstorm repository

In order to create branches, you need to be the owner of a repository. Since you are not the owner of the official Brainstorm repository, you will need to fork it to create your own copy where you are the owner. This is a simple one click step that can be performed from the official Brainstorm GitHub page: https://github.com/brainstorm-tools/brainstorm3. Simply click "Fork" at the top right of the page.

Important note: You are the sole owner of this new repository. You are free to do whatever you want with it. That also means you are in charge of keeping it up to date. New updates to Brainstorm will NOT be automatically pushed to you. If you want to run Brainstorm using your own fork, you will need to update your master branch with the official repository's master branch to get the latest changes. If you do not do this, your own master branch's last update will be the one at the time you clicked fork.