Skip to content

Latest commit

 

History

History
76 lines (47 loc) · 5.24 KB

CONTRIBUTING.md

File metadata and controls

76 lines (47 loc) · 5.24 KB

Table of Contents

Contributing to Brainbox

Things you need to be familiar with before contributing to Brainbox:

  • Fundamentals of Python programming and how to use NumPy for math
  • How to use Git and GitFlow to contribute to a repository
  • Our guidelines on how to write readable and understandeable code

Below is a guide which will take you from the ground up through the process of contributing to the brainbox software package. Some of these sections may already be familiar to you, but it may be worth skimming them again in case you've forgotten some of the nuances of using python, git, github, or unit tests.

Installing the right python environment (10 minutes)

TL;DR: We provide an environment.yml file. Use Anaconda to create an environment which only contains the packages Brainbox needs.

We suggest using Anaconda, which is developed by continuum.io, as your basis for developing Brainbox. Begin by downloading the most recent version of Python 3 Anaconda for your operating system. Install using the installation instructions on the Anaconda website, and make sure that you can interact successfully with the conda command in either a terminal (OS X, Linux) or in the Anaconda Prompt provided on Windows.

Once you have installed Anaconda, the next step is to create an environment for working with brainbox. This requires you to have the environment.yml file which lives in the top directory of this repository. We will just clone the whole repository now though, since you will need it later, using the following command on *nix systems:

git clone https://github.com/int-brain-lab/ibllib/
cd ./ibllib
git checkout brainbox

Note: please navigate to the folder where you want to run this command beforehand, e.g. /home/username/Documents if you want the brainbox repository to live in your Documents folder

For Windows users we recommend using git for Windows as a Windows TTL emulator, which will allow for you to run the above command without any changes. That software also includes a graphical git interface which can help new users.

Once you have cloned the repository and downloaded Anaconda, navigate to the top level of Brainbox where the environment.yml file is, then run the following command in a terminal or Anaconda prompt session:

conda env create -f environment.yml

Type "yes" when prompted and conda will install everything you need to get working on brainbox! After this you will need to run

conda activate bbx

if you are developing from the terminal, in order to activate the environment you just installed. Always do this when you create a new terminal to develop Brainbox! This way you don't code in packages that brainbox doesn't support!

Git, GitFlow, and you (15 minutes)

TL;DR: We use Git with a GitFlow workflow to develop Brainbox. Please create new feature branches of brainbox for writing code and then make a pull request to have it added to brainbox.

For those unfamiliar with it, Git is a system for version control, which allows you to make changes to whatever you put into it (Git isn't limited to just code!) that are:

  • Tracked (When?)
  • Revertable
  • Identifiable (Who? Why?)
  • Branching

That last bit is crucial to how we develop brainbox and how Git works.

Git allows for multiple versions of a repository (which is a glorified name for a folder of stuff) that can exist at the same time, in parallel. Each version, called a branch, contains its own internal history and lets you undo changes.

This way you can keep a version of your code that you know works (called master), a version where you have new stuff you're still working on (called develop in our repository), and branches for trying out specific ideas all at the same time.

For an explanation of the basics of Git, this guide by Roger Dudler is a necessary five-minute read on the basics of manipulating a repository.

Brainbox uses GitFlow as a model for how to organize our repository. This means that there are two main branches that always exist, master and develop, the latter of which we have renamed brainbox, as brainbox is a part of ibllib. brainbox is the basis for all development of the toolbox.

Writing code for Brainbox

We require all code in Brainbox to conform to PEP8 guidelines, with Numpy-style docstrings. We require all contributors to use flake8 as a linter to check their code before a pull request. Please check the .flake8 file in the top level of ibllib for an exact specification for how to set up your particular instance of flake8.

[MORE GUIDELINES HERE PLEASE]