Skip to the content.

Developing and contribnuting to BrainVisa projects using git

General workflow

Many components of BrainVISA now have their source managed with Git, and are hosted on Github. If you are new to Git, you should read the short GitHub Git handbook. You can find more information in the Git and GitHub learning resources.

BrainVISA projects are managed by brainvisa-cmake, a tool to manage the whole development process, including sources management, configuration and build, tests, and more. The main tool of brainvisa-cmake is bv_maker.

For sources management, bv_maker relies on standard source versioning control software, namely subversion or git. It mainly adds a multi-project management layer.

Setup a build environment

This can be done either using casa-distro which provides build environments in virtual containers, or on a host system, after installing all needed development libraries (list not provided here…), using brainvisa-cmake.

Read-only update access

While not developing, updating the codes is just a matter of using:

bv_maker sources

see bv_maker sources. Or to update the code and rebuild the needed modifications, simply:

bv_maker

either on the host system (for a host build) or in casa-distro.

Modifying / developing

When starting to develop into a project managed by git, there are two possible modes: either fork the project on GitHub, or create a feature branch on the origin repository (if appropriate access rights are granted).

Several use cases

  fix a bug develop a feature
user has push access to origin/master may push to master or feature branch feature branch with or without fork
user has push access to origin/<feature> push to feature branch with or without fork feature branch with or without fork
no push access feature branch with fork feature branch with fork

Basically we handle multiple projects the same way as working in a single project, we just need to perform commit / push / pull request operations multiple times. But we just needed tools to help automatize at least update operations in multiple projects.

what bv_maker sources does / should do:

The following operations are not performed by bv_maker sources:

bv_maker 2 vs 3

With bv_maker v2, working on repositories managed by bv_maker sources used to have one peculiarity: bv_maker used to set up the repositories in detached mode, which means that no local branches are created in the repositories. This means that you have to create your own branch as soon as you want to commit changes, using git checkout -b <branchname>.

With bv_make v3, this behavior is no longer used: repositories are completely cloned, then the selected branch (master or integration) is activated.

For client repositories created using bv_maker 2 and now used with bv_maker 3, the detached branch mode is still maintained, and will be until you switch to (checkout) a “real” branch. The difference is that repositories will be fully fetched (as in bv_maker 3).

Helper tools

bv_maker status

shows the status of source branches in multiple projects (current branch, modified code, staged changes, local commits not pushed to a remote, diverging branches and remotes…)

There is also possibility to use vcstool

Working with feature branches

When the feature is done and OK:

without a fork (needs permission to create branches on origin)

When the feature is done and OK:

all users will see the feature branch, please don’t make thousands of feature branches, and be careful to clean them up once they are merged.

Finish a feature

with a personal fork

with a feature branch on the origin remote

Possibly needs some specific permissions. If you cannot perform some steps, please ask someone who has the permissions (the person who merges the pull request).

Howto / common situations

I have started to modify source code without checking the state / branch of my repository

git stash
git checkout -b new_branch
git stash pop
git add <files>
git commit
[ git push ]

same but I have also commited locally, on the wrong branch

git keeps asking for a login / password for every push

In other words, https / ssh URL or github projects:

URLs in github may use the https protocol (not needing a ssh key, but git will ask for a password every time you push), or the ssh protocol, using a ssh key which will avoid the need for a password every time. bv_maker uses https by default because it cannot assume you have a github account and have provided a ssh key in github. But it’s more convenient to work with ssh. So we have to switch when we have a github account and a ssh key registered in it. There is a tool to switch automatically:

git config --global url."git@github.com:".insteadOf "https://github.com/"

This tells git to automatically replaces URLs starting with https://github.com/ with their git@github.com: counterpart.

Otherwise it is possible to set individually the git remote URLs to use ssh rather than https, but this will only work for personal remotes (a fork), not on origin for projects known by brainvisa-cmake, because bv_maker will reset the origin URL when updating sources to the URL in the “official” projects list.

git remote set-url johndoe git@github.com:johndoe/brainvisa-cmake.git

The last option is to make git store credentials unencrypted in the .git directory of the project. You have to do so for each project, and in brainvisa-cmake, each declared branch (bug_fix / trunk etc.) since each is a separate clone of the git repos. Then on the next update (bv_maker sources) git will ask for username and password, still for each project directory, and then store them and don’t ask again the next time:

git config credential.helper store

Note that, when developing in Casa-Distro containers, it is still possible to share the personal ssh keys, see the Casa-Distro technical doc

Releasing toolboxes

Starting from BrainVisa 5.0, users will install the BrainVisa distribution as virtual machine or container images. The older installer is gone, so is the modularity (nobody was actually using the modular struture which was very difficult to maintain, and no toolbox developer have actually used it to distribute their toolbox).

Installing a toolbox in BrainVisa

Toolboxes will be released as ZIP files which will be unpacked on top of an existing BrainVisa distribution.

Container image distributions are read-only by default (singularity .sif files), but there are options for users to copy the distribution on the host filesystem with read/write permissions, using the bv configuration user interface. This bv install interface also allows to download additional distributions (distro), which is one way to install toolboxes if they are available on the BrainVisa web site, or at another location if their URL is entered there.

To release a toolbox, a developer thus has to make a ZIP file containing the files to be added on top of the BrainVisa distribution.

Creating a toolbox release

When developing inside casa-distro, the build infrastrutcture is the same as the official BrainVisa release, thus compatibility is ensured.

Using bv_maker to build projects, the toolbox files should be handled in the infrastructure.

The developer has to copy the built files into an install directory, and zip its contents. From the build directory, if the toolbox project is named toolbox for instance, it is done using the following commands:

make install-toolbox BRAINVISA_INSTALL_PREFIX=/casa/host/install
cd /casa/host/install
zip -r ../toolbox-5.0.0-ubuntu-18.04.zip *

(here in this example, we want to release the toolbox for the version 5.0.0 of BrainVisa, and we are buiding in a container based on an Ubuntu 18.04 system).

Then publish the ZIP file, and users just need to download it and unzip it into their read/write install directory, which is /casa/host/install/ in singularity distributions, and can be /casa/install in VirtualBox distributions. As said before, installig can also be handled by the bv GUI install options, if the toolbox can be downloaded in the expected directories tree in a web server.

What if additional third-party software or libraries are required for the toolbox

This case is not really automated up to now.