Contributing

How to contribute to this project.

Fork this repository

Fork this repository before contributing.

Next, clone your fork to your local machine, keep it up to date with the upstream, and update the online fork with those updates.

git clone https://github.com/YOUR-USERNAME/grafanarmadillo.git
cd grafanarmadillo
git pull origin main

Install for developers

Create a dedicated Python environment where to develop the project.

If you are using pip follow the official instructions on Installing packages using pip and virtual environments, most likely what you want is:

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

Install the package in develop mode, and also tox.

python setup.py develop
pip install dev_requirements.txt

Make a new branch

From the main branch create a new branch where to develop the new code.

git checkout main
git checkout -b new_branch

Develop the feature and keep regular pushes to your fork with comprehensible commit messages.

git status
git add (the files you want)
git commit (add a nice commit message)
git push origin new_branch

While you are developing, you can execute tox as needed to run your unittests or inspect lint, etc. See the last section of this page. If you want things to build a bit faster, you can set the pythonpath and run pytest directly.

export PYTHONPATH=./src
python3 -m pytest tests

Many of the tests will rely on a test Docker container to integrate with a Grafana instance. By default this only runs on Linux, but can be forced by setting “do_containertest” to “True”

Update CHANGELOG

Update the changelog file under docs/CHANGELOG.rst with an explanatory bullet list of your contribution. Add that list right after the main title and before the last version subtitle:

Changelog
=========

* here goes my new additions
* explain them shortly and well

vX.X.X (1900-01-01)
-------------------

Also add your name to the authors list at docs/AUTHORS.rst.

Pull Request

Once you are finished, you can Pull Request you additions to the main repository, and engage with the community. Please read the PULLREQUEST.rst guidelines first, you will see them when you open a PR.

Before submitting a Pull Request, verify your development branch passes all tests as described bellow . If you are developing new code you should also implement new test cases.

Uniformed Tests with tox

Thanks to Tox we can have a unified testing platform where all developers are forced to follow the same rules and, above all, all tests occur in a controlled Python environment.

With Tox, the testing setup can be defined in a configuration file, the tox.ini, which contains all the operations that are performed during the test phase. Therefore, to run the unified test suite, developers just need to execute tox, provided tox is installed in the Python environment in use.

pip install tox

Before creating a Pull Request from your branch, certify that all the tests pass correctly by running:

tox

These are exactly the same tests that will be performed online in the Github Actions.

Also, you can run individual environments if you wish to test only specific functionalities, for example:

tox -e lint  # code style
tox -e build  # packaging
tox -e docs  # only builds the documentation
tox -e prreqs  # special requirements before Pull Request
tox -e py38