Contribution guidelines

If you are interested in contributing to |sname| development or running its latest source code, you should install the (GitLab) sources following the Installing TimageTK from sources procedure.

Requirements

First install git & gitk development tools:

  • Ubuntu & Debian:

    $ sudo apt-get install git gitk
    
  • Fedora & Redhat:

    $ sudo yum install git gitk
    
  • MacOSX:

    sudo port install git-core +doc +bash_completion +gitweb
    

Workflow

General workflow

Edit the python code, but do not forget to write documentation and tests before submitting a merge request.

You can also contribute by raising issues you face with the code on the dedicated area of the GitLab repository.

Git workflow

Warning

NEVER EVER work on master, always on a branch!

  1. Clone the official repository:

    git clone git@gitlab.inria.fr:mosaic/timagetk.git
    
  2. Create development branch: #. Get latest version of origin/master:

    git checkout master  # go to your local master branch
    git pull master  # update it with origin/master
    
    1. Create your new branch (choose an explicit name):

      git checkout -b wip_my_branch  # create local branch wip_my_branch
      git push --set-origin origin wip_my_branch  # attach branch wip_my_branch to origin
      
  3. Work on your modifications: #. To add a new file mynewfile.py to git version control system:

    git add mynewfile.py
    
    1. To commit changes to git repository:

      git commit
      
    2. To push changes to git repository:

      git push origin wip_my_branch  # push modification to origin/wip_my_branch
      
  4. Prepare your work for merging: #. Get latest version of origin/master:

    git checkout master  # go to your local master branch
    git pull origin master  # update it with origin/master
    
    1. It is safer to create a new branch for rebase:

      git checkout wip_my_branch  # go to your local development branch wip_my_branch
      git checkout -b my_branch  # create and checkout new branch my_branch
      git rebase master  # rebase local master branch with my_branch
      
    2. If master has diverged during your work, fix conflicts (use meld), then say to git that conflicts are resolved:

      git add file1
      git rebase --continue  # to finish rebase
      
  5. Merge branch:

    git checkout master  # go to your local master branch
    git pull origin master  # update it with origin/master
    git merge --no-ff my_branch  # use ‘--no-ff’ (no fast forward) to create a merge commit
    git push origin master  # Then push it to origin/master
    
  6. Finalization, check if you find all yours commits on origin/master, if yes:

    git branch --delete my_branch  # delete local development branch
    git push origin :my_branch  # delete development branch on origin
    

Other tools

Merge/rebase conflicts

To solve merge or rebase conflicts, we advise to either use the web IDE or to use a visual diff and merge tool such as meld.

For Ubuntu and Debian users:

sudo apt install meld

Git version control

Although gitk is a lightweight version control GUI, it is somewhat ugly and old. We advise to use gitkraken (the free version) availables for Linux and and MacOSX.

For Ubuntu users, you can find a packaged version in snap:

sudo snap install gitkraken

All supported platforms can be found here.