Contributing

Issues

We use the GitHub issue tracker for reporting issues. Before opening a new issue, ensure the bug was not already reported by searching on Issue tracker first.

If you’re unable to find an open issue addressing the problem, open a new one. Be sure to include a title and clear description, as much relevant information as possible, and a code sample or an executable test case demonstrating the expected behavior that is not occurring.

If you are looking to contribute for the first time, some issues are tagged with the “good first issue” label and are easy targets for newcomers.

Pull-requests

When opening a pull-request, make sure that:

  • You write a comprehensive summary of your problem and the solution you implemented.

  • If you update or fix your pull-request, make sure the commits are atomic. Do not include fix-up commits in your history, rewrite it properly using e.g. git rebase –interactive and/or git commit –amend.

  • We recommend using git pull-request to send your pull-requests.

All sent pull-requests are checked using GitHub Actions, which is in charge of running the tests suites. There are different scenarios being run: PEP 8 compliance tests, doc8 lint, upgrade tests, unit and functional tests.

All pull-requests must be reviewed by members of the Gnocchi project.

When a pull-request is approved by a team member and the GitHub Actions confirms that all the tests run fine, the patch will be merged.

The Gnocchi project leverages Mergify in order to schedule the merge of the different pull-requests. Mergify is in charge of making sure that the pull-request is up-to-date with respect to the master branch and that the tests pass. Pull-requests are always merged in a serialized manner in order to make sure that no pull-request can break another one.

Gnocchi’s Mergify dashboard shows the current status of the merge queue.

Running the Tests

Tests are run using tox. Tox creates a virtual environment for each test environment, so make sure you are using an up to date version of virtualenv.

Different test environments and configurations can be found by running the tox -l command. For example, to run tests with Python 3.9, PostgreSQL as indexer, and file as storage backend:

tox -e py39-postgresql-file

To run tests with MySQL as indexer, and Ceph as storage backend:

tox -e py39-mysql-ceph

In order to run the tests like they do in the CI, you could create a user with UID 1001 and GID 1001 and run a command like this

::

docker run -v $(pwd):/github/workspace gnocchixyz/ci-tools:latest tox

Make sure the machine executing the tests has as least 4 GB of RAM.