How to contribute?

Setup environment

If you want to start contributing to this project, you will need to set up your development environment. The project uses python 3.10.7. We recommend installing it using a python environment (see step 2).

First start by forking this repository Go to our Gitlab page and hit the fork button. Then you need to clone your fork on your machine:

git clone https://your.gitlab.website/your.user.name/dyn/viz.git dyn-viz
cd dyn-viz
git remote add upstream https://gitlab.com/decide.imt-atlantique/dyn/viz.git

Then we recommend that you create a separate python environment for this project using for example pyenv and pyenv-virtualenv (see Python environment for installation details):

pyenv install 3.10.7         # Install python 3.10.7 with pyenv
pyenv virtualenv 3.10.7 dyn  # Create a python 3.10.7 virtualenv called 'dyn'
pyenv local dyn              # Set up 'dyn' as the environment to use in the project folder

You can then install the system requirements (required for building the doc):
```
sudo apt install pandoc
```
You can then install the required python packages:
```
make install
```
Note

This command uses pip, if you didn’t follow step 2, you need to have it installed. Otherwise you can use the project requirements.txt file and install them the way you want.

Alternatively, you could replace steps 2 through 4 by using our VS Code devcontainer. You need the docker engine installed for that.

Install the requirements to use dev containers inside VS Code
Simply open the project folder in VS Code
Click the green button located in the bottom-left corner of VS Code (or open the command palette)
Select Remote Containers - Reopen in Container
VS Code will now reload and start initializing the containers. Wait for it to complete. This may take a while the very first time as pip dependencies must be installed.

We provide a pre-commit hook that will test your code when commiting. It tests the linters and cancels the commit if they fail. You can set it up easily:

chmod +x pre-commit         # make sure it has execution rights
cp pre-commit .git/hooks/.  # install pre-commit hook

You are ready to go! If you are unsure, you can run some of the tests included in the Makefile.

Development

As mentionned earlier, the main branch is the most up-to-date version of the project. You should always start from this branch when developing a new feature or bugfix. And any change made shall ultimately be merged on this branch.

Identify an issue

It is a good practice to keep an issue and bug tracker as complete and up-to-date as possible (see this).

So it is recommended you start any development by creating a new issue, or selecting an open issue on the gitlab repository. You can then assign this issue to yourself so other contributors know this issue is being taken care of.

Create temporary branch

You should create a branch specific to the development you want to do, this branch shall spans from the up-to-date main branch:

git checkout main              # get on 'main' branch
git pull                      # update branch so it matches its remote state
git checkout -b nnnn-xxxx     # create and get on a feature branch (when developing a new feature 'xxxx' identified by issue 'nnnn')

Alternatively, you can go on Gitlab, select the issue you are working on, and click on the drop-down part of the blue button that says “create merge request” and select “create branch” instead. Make sure the new branch spans from main. Then you can work on this branch:

git fetch                     # fetch all changes on the remote repository
git checkout nnnn-xxxx        # get the temporary branch (replace its name with the one you chose on gitlab)

Working on temporary branch

When working, remember to commit and push your changes often. If working on a specified issue, always reference that issue in the commit messages (see :ref:`this <contributing/repository:Commits>`). Also whenever an issue has been resolved, mention it in the message of the commit solving the issue. We recommend that you develop alongside the followings:

source code (see the coding conventions)
documentation (see this for more details)
- doc-string (see this for more details)
- comments (see this for more details)
tests (see this for more details)
notebooks showing how a high-level use of your newly added features (see this for more details)

We also recommend you test your code as often as possible, using the provided Makefile targets.

You can keep up with other branches progress, using the following command: git fetch

Merging branch on common main branch

When your development is over and you think it can be merged back into the main branch, you shall check the following:

Your changes actually accomplish what they were intended (e.g the issue related to the branch is resolved)
Your code passes the linters and tests
The documentation of your changes is complete
The changes have been appended to the top of the changelog
The package requirements are up-to-date (both in the requirements.txt and setup.py files)
All your changes have been pushed on the online repository

Then you can open a new merge request on gitlab, requesting the merge of your branch on the main branch. Please use the following options:

Delete source branch after merge
Do not stash changes before merge

Then your merge request will be checked and only applied when approved by a project maintainer. While the merge request is open, you can add commits to it, and interact with other developers about the request. Until the merge request is approved and applied, you may have to come back to it and perform some changes.

However in the meantime, you can start working on a new feature.

We recommend to start from the main branch, however in the case where the previous merge request has not yet been accepted and your new feature will depend on it, you may start a new branch spanning from your not-yet-merged branch.

When the merge is applied, you can delete your local branch and its remote tracking:

git branch -d nnnn-xxxx
git branch -d -r origin/nnnn-xxxx

Release a new version

Warning

This section is obsolete and based on another git workflow

Todo

update section to current workflow

When enough features have been added, or if a package-breaking bug has been fixed, we may want to release a new version of the package. We will then check the followings:

The code passes the linters and tests
The documentation is complete
The changes have been appended to the top of the changelog
A version number is associated to the release and appended at the top of the changelog and changed in VERSION
The package requirements are up-to-date (both in the requirements.txt and setup.py files)

For item 4, we use bump2version and decide which type of release we are doing (see changelog section). The release of a major version should not be taken lightly and needs to be debated. Backwards breaking but necessary changes can be bundled on a future branch and only released when significant or the timing is right.

Then we can open a new merge request on gitlab, requesting the merge of the main on the main branch. Please use the following options:

Delete source branch after merge
Do not stash changes before merge

Then our merge request will be checked and only applied when approved by a project maintainer. While the merge request is open, we can add commits to it, and interact with other developers about the request. Until the merge request is approved and applied, we may have to come back to it and perform some changes.

When the merge request is approved and applied, the gitlab pipeline for the main branch will include a new extra job to deploy the new version of the package on PyPI which is triggered manually.

Then to ensure the correspondence between the release on gitlab and PyPI, you need to tag the commit of the release:

git checkout main
git pull
git tag {a}.{b}.{c}
git push --tags

The tag can also be applied from the gitlab web page.