Thank you for considering contributing to ilastik, we really appreciate it. The following text equips you with knowledge that makes contributing to ilastik easier.

• Development Environment
• Workflow
• Coding Style

1. Download and install Git, GitHub CLI, and the latest 64-bit Miniforge.

   • Windows: all following commands should be executed in the Anaconda Prompt from the Start Menu.
   • Linux: Git might be already preinstalled, GitHub CLI might be available in your system package manager.
   • macOS: Git is already preinstalled, GitHub CLI is available in Homebrew.

2. Fork and clone repositories:

   gh repo fork --clone=true --remote=true ilastik/volumina
   gh repo fork --clone=true --remote=true ilastik/ilastik
   

   If you already forked repositories before, just clone them:

   gh repo clone volumina
   gh repo clone ilastik
   

3. If you have an existing conda installation, you can use it for ilastik development, but configure it to use strict channel priority.

   conda config --set channel_priority strict
   

4. Create a new environment and install dependencies:

   # from within the ilastik folder
   conda deactivate
   conda env remove --name ilastik
   conda env create --name ilastik --file dev/environment-dev.yml
   

5. Install repositories as packages in development mode:

   conda activate ilastik
   # from the folder containing ilastik and volumina
   pip install --editable ilastik
   pip install --editable volumina
   

6. Install pre-commit hooks:

   conda activate ilastik
   
   cd volumina
   pre-commit install
   cd ..
   
   cd ilastik
   pre-commit install
   cd ..
   

7. Launch ilastik:

   conda activate ilastik
   cd ilastik
   python ilastik_scripts/ilastik_startup.py
   

We use GitHub Flow workflow without the Deploy step.

The whole ilastik project is split into 2 repositories: ilastik and volumina. Therefore, for some changes you need to repeat the instructions twice in the corresponding directories.

1. Make sure that your local and remote main branches are synced with the upstream.

   git pull --ff-only upstream main:main
   git push origin main
   

2. Create a new branch from main:

   git switch --create your-branch-name-here main
   

3. Write some code, and, if possible, add tests for your changes.

4. Run the test suite for all repositories:

   cd volumina
   pytest
   cd ..
   
   cd ilasitk
   pytest --run-legacy-gui
   cd ..
   

5. Commit the changes; see https://chris.beams.io/posts/git-commit/ on how to write a good commit message.

6. Create a pull request:

   gh pr create --web
   

   • If you have changes in multiple repositories, create multiple pull requests, and then append the following paragraph to each one:

     Related: OTHER_PULL_REQUEST_URL_HERE
     

   • If your changes require feedback, create a draft pull request (select the type from the dropdown list on the green button).

7. Discuss your work with the other people, and wait for the approval from maintainers.

8. After your pull request has been merged, remove your local branches:

   git branch --delete your-branch-name-here
   

   You can also remove your remote branches by clicking "Delete branch" in the pull request web page, or running the following:

   git push --delete origin your-branch-name-here
   

Many users with different backgrounds have contributed to ilastik in the past. Code quality and coding styles can be quite different throughout the code-base.

In general, when working on an existing file, please try to deduce the used coding style from what you see there, and adapt to it while working on this particular file.

For new files, we adhere to the Google Python style guide and black code style.

Note: please refrain from including changes by some automatic tools on existing code in your pull requests. We would like to preserve the history there. But please run those tools on the code you are contributing :)

• The file .git-blame-ignore-revs holds some commits that were generated automatically and only affected code style. These commits can be ignored in git-blame:

  git blame --ignore-revs-file .git-blame-ignore-revs <some-file>
  

  This setting can also be made permanent for your local repo:

  git config blame.ignoreRevsFile .git-blame-ignore-revs