Skip to content

Latest commit

 

History

History
115 lines (85 loc) · 8.16 KB

CONTRIBUTING.md

File metadata and controls

115 lines (85 loc) · 8.16 KB
Raw

Contributing to Brainstorm

Thank you for contributing to Brainstorm!

This repository (repo) holds the source code for the Brainstorm application.

When contributing, please first discuss the change you wish to make in one of the three following ways:

Contributions to this repository include:

To know other ways in which you can collaborate with Brainstorm, visit the Contribute page.

MATLAB resources

Brainstorm is developed with MATLAB (and bit of Java for the GUI). This is a brief list of resources to get started with MATLAB if you are new or come from a different programming language:

Git and GitHub resources

Before starting a new contribution, you need to be familiar with Git and GitHub concepts like: commit, branch, push, pull, remote, fork, repository, etc. There are plenty resources online to learn Git and GitHub, for example:

How to contribute

We use the GitHub Flow as guideline for contributions. Thus, the general process to contribute to Brainstorm consists of 7 steps:

  1. Create your copy of the official Brainstorm repo

    Fork the official Brainstorm repo (https://github.com/brainstorm-tools/brainstorm3) to your GitHub account. This will create your Brainstorm repo in your GitHub account. Then clone your Brainstorm repo (https://github.com/YOUR-USERNAME/brainstorm3) to your computer. These actions will create a copy of the Brainstorm repo in your GitHub account and a local repo in your computer so you can freely modify it without affecting the official Brainstorm repo.

    Fork the official Brainstorm repo in https://github.com/brainstorm-tools/brainstorm3, then:

    $ git clone https://github.com/YOUR-USERNAME/brainstorm3

  2. Link your local repo to the official Brainstorm repo

    In your local repository, add the official Brainstorm repo as a remote.

    $ git remote add official https://github.com/brainstorm-tools/brainstorm3

    At this point the remote origin refers to your forked repo (in your GitHub account), and the remote official to the repo in https://github.com/brainstorm-tools/brainstorm3. By doing this you can pull the official Brainstorm repository to keep your repo synchronized with the most recent version of Brainstorm.

    $ git checkout master    
$ git pull official master
$ git push origin master

    ⚠️ Perform your changes in the latest version of Brainstorm to facilitate the contribution process.

  3. Create a branch in your local repo

    Create a branch in your local repo. This branch is the one that will be used for your contribution.

    git checkout -b fix-something

    💡 Make a separate branch for each set of unrelated changes.

  4. Work on the desired changes

    Your branch is a safe place to make the changes that you desire.

    git checkout fix-something

    Commit your changes to your local branch.

    • Give each commit a descriptive message to help you and the maintainers to understand what changes the commit contains.
    • Do not push your commits until you're happy with them, or you have good reason to do it.

    💡 Working locally give you the freedom of rewriting your commit history to clean it up. A clean commit history simplifies the contribution process. See: Git tools rewriting history for more info.

  5. Done with the changes

    When you're done the desired changes. The next step is to push your local branch (if you haven't) to your remote origin repo.

    To push your local branch to the remote origin for the first time, you need to set the upstream. This process creates a branch in your remote repo, links it to your local branch, and pushes your local changes to the repo in your GitHub account.

    git push --set-upstream origin fix-something

    Once the upstream is set, additional local commits can be push with:

    git push origin fix-something

  6. Create a new Pull Request

    Once you're happy with all the changes that you have done, and you have pushed them to your remote repo, using the GitHub website, create a Pull Request (PR) from your remote branch to the master branch in the official Brainstorm repo.

    ⚠️ For greater collaboration, select the option Allow edits by maintainers before creating your PR. This will allow Brainstorm maintainers to add commits to your PR branch before merging it. You can always change this setting later.

image

  1. Code review

    Once you have created a PR, we will start a review on the changes and provide feedback to have all the proposed changes inline with Brainstorm. When your PR is approved, the next step is to merge your work to the official Brainstorm repo.

Do not hesitate in contacting us if you have any question.