Contributing

You can contribute to the project in multiple ways:

* Write documentation

* Implement features

* Fix bugs

* Add unit and functional tests

* Everything else you can think of

Development workflow

Before contributing, please make sure you have `pre-commit <https://pre-commit.com>`_

installed and configured. This will help automate adhering to code style and commit

message guidelines described below:

.. code-block:: bash

Please provide your patches as GitHub pull requests. Thanks!

Commit message guidelines

We enforce commit messages to be formatted using the `conventional-changelog <https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines>`_.

This leads to more readable messages that are easy to follow when looking through the project history.

Code-Style

We use black as code formatter, so you'll need to format your changes using the

`black code formatter

<https://github.com/python/black>`_. Pre-commit hooks will validate/format your code

when committing. You can then stage any changes ``black`` added if the commit failed.

To format your code according to our guidelines before committing, run:

.. code-block:: bash

Running unit tests

Before submitting a pull request make sure that the tests and lint checks still succeed with

your change. Unit tests and functional tests run in GitHub Actions and

passing checks are mandatory to get merge requests accepted.

Please write new unit tests with pytest and using `responses

<https://github.com/getsentry/responses/>`_.

An example can be found in ``tests/unit/objects/test_runner.py``

You need to install ``tox`` (``pip3 install tox``) to run tests and lint checks locally:

.. code-block:: bash

Running integration tests

Integration tests run against a running gitlab instance, using a docker

container. You need to have docker installed on the test machine, and your user

must have the correct permissions to talk to the docker daemon.

To run these tests:

.. code-block:: bash

When developing tests it can be a little frustrating to wait for GitLab to spin

up every run. To prevent the containers from being cleaned up afterwards, pass

`--keep-containers` to pytest, i.e.:

.. code-block:: bash

If you then wish to test against a clean slate, you may perform a manual clean

up of the containers by running:

.. code-block:: bash

By default, the tests run against the latest version of the ``gitlab/gitlab-ce``

image. You can override both the image and tag by providing either the

``GITLAB_IMAGE`` or ``GITLAB_TAG`` environment variables.

This way you can run tests against different versions, such as ``nightly`` for

features in an upcoming release, or an older release (e.g. ``12.8.0-ce.0``).

The tag must match an exact tag on Docker Hub:

.. code-block:: bash

A freshly configured gitlab container will be available at

http://localhost:8080 (login ``root`` / password ``5iveL!fe``). A configuration

for python-gitlab will be written in ``/tmp/python-gitlab.cfg``.

To cleanup the environment delete the container:

.. code-block:: bash

Releases

A release is automatically published once a month on the 28th if any commits merged

to the main branch contain commit message types that signal a semantic version bump

(``fix``, ``feat``, ``BREAKING CHANGE:``).

Additionally, the release workflow can be run manually by maintainers to publish urgent

fixes, either on GitHub or using the ``gh`` CLI with ``gh workflow run release.yml``.

**Note:** As a maintainer, this means you should carefully review commit messages

used by contributors in their pull requests. If scopes such as ``fix`` and ``feat``

are applied to trivial commits not relevant to end users, it's best to squash their

pull requests and summarize the addition in a single conventional commit.

This avoids triggering incorrect version bumps and releases without functional changes.

The release workflow uses `python-semantic-release

<https://python-semantic-release.readthedocs.io>`_ and does the following:

* Bumps the version in ``__version__.py`` and adds an entry in ``CHANGELOG.md``,

* Commits and tags the changes, then pushes to the main branch as the ``github-actions`` user,

* Creates a release from the tag and adds the changelog entry to the release notes,

* Uploads the package as assets to the GitHub release,

* Uploads the package to PyPI using ``PYPI_TOKEN`` (configured as a secret).

For guidelines for contributing to ``python-gitlab``, refer to `CONTRIBUTING.rst <https://github.com/python-gitlab/python-gitlab/blob/master/CONTRIBUTING.rst>`_.