.. _contributing:

Contributing
============

Reporting issues
----------------

This project uses the gitlab issue tracker here: https://git.astron.nl/RD/trap/-/issues.
Any issue can be raised here regarding bugs or new features.

Installing from source
----------------------

The following quick start guide assumes you are running on a unix machine.

We start by cloning from `GitLab <https://git.astron.nl/RD/trap>`_.

>>> git clone https://git.astron.nl/RD/trap.git

Then go into the folder

>>> cd trap

Now let's create and activate a venv to use:

>>> python3 -m venv venv
>>> source venv/bin/activate

Or if you are using Conda:

>>> conda create --name trap_env python=3.11
>>> conda activate trap_env

Upgrade pip and install the package with the additional 'doc' and 'test' dependencies.
Here the ``-e`` flag will prevent TraP itself from being installed in the virtual environment
but should point to the source files we just checked out. This makes sure that any updates you make
to the source files will be reflected when importing the package from your virtual environment.

>>> python3 -m pip install pip
>>> python3 -m pip install -e .[doc,test,view]

Now your custom-build venv is ready for use!

Testing and building documentation
----------------------------------

In order to run tests or build documentation we need some test data. Download the test data by running:

>>> git submodule update --init --recursive

Run the tests using pytest:

>>> python3 -m pytest tests

You can build the docs lcoally using

>>> sphinx-build docs/source build/sphinx/html -v

or if sphinx-build is not available to you,
install the ``python3-sphinx`` package on your system or try:

>>> python3 -m sphinx.cmd.build docs/source build/sphinx/html

Manually Building the Docker Image
----------------------------------
From the repository root, build the Docker image using the following commands:

.. code-block:: bash

    export DOCKER_BUILDKIT=1
    docker build --build-arg TRAP_VERSION=0.1.0.dev -t trap-test -f docker/Dockerfile .

- `--build-arg TRAP_VERSION` sets the version of the package for this build.
- `-t trap-test` tags the image as `trap-test`.
- The Dockerfile is located at `docker/Dockerfile`.

Code formatting
---------------

`Black` and `isort` are used for code formatting.
These packages are installed when the [test] argument is used during installation (see section [Installing From Source](#installing-from-source)).
Pytest-black will test the format of the python files.
Code that does not pass the test should be reformatted using black and isort like so:

>>> python3 -m black trap tests
>>> python3 -m isort trap tests

It is recommended to install the pre-commit hook, which will check the code format on commit and fix it if needed

>>> pre-commit install

This process ensures the same code standards are enforced all over the codebase.

Merge requests
--------------

After testing and commiting your changes, check out a new branch and push it to origin.
Don't forget to make a merge request ;)
The merge request will be reviewed by one of the maintainers of the project.

Thank you for contributing!

Issues
------

If you have any feedback or found a bug, please submit a ticket in the issue tracker: https://git.astron.nl/RD/trap/-/issues

Deploying
---------

Deploying TraP involves two separate stages:
 - building the Docker image and creating a git release branch and tag
 - releasing on PyPI

This is a manual step. Once the automated tests and linters pass, the option to manually run
the `build_docker` job appears. Don't just run it, but first specify the version variable in the UI.
Click on the job and add the variable "VERSION" and set the value to the desired release version.
It has to be PEP-440 complient, or the job will fail. You can rerun with a different value if that is the case.
This job will then
1. build and push a Docker container with the supplied tag, also overwriting 'latest'
2. update all references to docker containers in the cwl files
3. commit to a new release branch, tag and push to git

The PyPI releaes job (called `deploy`) is available after a tag. Since the `build_docker` job ends up pushing a tag,
the `deploy` job is available for manual trigger afterwards. In principle it is possible to tag a commit and start the
`deploy` job, just as it is possible to publish to PyPI directly from your local command line, it is not the intended flow.