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 :ref:`python environment ` (see step 2). 1. 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: .. code:: bash git clone https://your.gitlab.website/your.user.name/dyn/benchmark.git dyn-core cd dyn-core git remote add upstream https://gitlab.imt-atlantique.fr:networks/dyn/benchmark.git 2. Then **we recommend that you create a separate python environment for this project** using for example *pyenv and pyenv-virtualenv* (see :ref:`Python environment ` for installation details): .. code:: bash 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 3. You can then install the system requirements (required for building the doc): .. code:: bash sudo apt install pandoc 4. You can then install the required python packages: .. code:: bash 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. 1. Install the `requirements `__ to use dev containers inside VS Code 2. Simply open the project folder in VS Code 3. Click the **green button** located in the bottom-left corner of VS Code (or open the command palette) 4. Select **Remote Containers - Reopen in Container** 5. 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 :ref:`linters ` and cancels the commit if they fail. You can set it up easily: .. code:: bash 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 :ref:`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 :doc:`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: .. code:: bash 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: .. code:: bash 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 `). 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 :ref:`coding conventions `) - documentation (see :ref:`this ` for more details) - doc-string (see :ref:`this ` for more details) - comments (see :ref:`this ` for more details) - tests (see :ref:`this ` for more details) - notebooks showing how a high-level use of your newly added features (see :ref:`this ` for more details) We also recommend you test your code as often as possible, using the provided :ref:`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: 1. Your changes actually accomplish what they were intended (e.g the issue related to the branch is resolved) 2. Your code passes the :ref:`linters ` and :ref:`tests ` 3. The :ref:`documentation ` of your changes is complete 4. The changes have been appended to the top of the :ref:`changelog ` 5. The package requirements are up-to-date (both in the ``requirements.txt`` and ``setup.py`` files) 6. 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: .. code:: bash 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 on our `package registry `__. We will then check the followings: 1. The code passes the :ref:`linters ` and :ref:`tests ` 2. The :ref:`documentation ` is complete 3. The changes have been appended to the top of the :ref:`changelog ` 4. A version number is associated to the release and appended at the top of the :ref:`changelog ` and changed in ``VERSION`` 5. 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 :ref:`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 our `package registry `__ 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: .. code:: bash git checkout main git pull git tag {a}.{b}.{c} git push --tags The tag can also be applied from the gitlab web page.