Contributing to Nagiosplugin
============================

Getting the source
------------------

The source can be obtained via git from
https://github.com/mpounsett/nagiosplugin.git::

   git clone https://github.com/mpounsett/nagiosplugin.git

This package supports installation in a virtualenv::

   python3 -m venv .
   pip install -e .


Making Changes
--------------

This project uses the `Git-flow workflow`_, approximately as laid out by
Vincent Driessen in 2010.  New development should be done in feature branches,
which are branched off of the `develop` branch.  PRs should be sent to
`upstream:develop`.

.. _Git-flow workflow: https://nvie.com/posts/a-successful-git-branching-model/

Consider whether your change updates or fixes any existing issues.  Include
the appropriate "fixes" or "updates" entry in your PR description so that the
issue is updated.   If your change does not reference an existing issue,
consider creating an issue to link it to.

The project uses PEP8 as its style guide. All changes should be checked
against PEP8 before committing, and commits **MUST** conform to PEP8 before
sending a PR.  PEP8 tests can be run with the `tox -e ruff` command (see
**Tests** below for details on setting up the tox environment).  PRs that
fail PEP8 compliance will be refused.

Note that, at present, much of the old codebase gets warnings related to
the `pylint` and `pydocstyle` tests.  Your changes must not introduce any
**new** warnings from these tests.

If your change is a new feature, or otherwise alters the behaviour of
`nagiosplugin`, update the relevant section of the documentation and include
that in your PR.

Tests
-----

**nagiosplugin** tests are run by `tox`_, which is configured to expect all of
the supported `python` versions to be present.  The easiest way to accomplish
this is by installing and using `pyenv`_.  

.. _tox: https://tox.readthedocs.io/en/latest/
.. _pyenv: https://github.com/pyenv/pyenv

Once you have `pyenv` set up, make sure you have each of the supported
versions of python specified by the `envlist` in `tox.ini`.  This will likely
look something like::

   pyenv install 2.7.18
   pyenv install 3.7.17
   pyenv install 3.8.20
   pyenv install 3.9.22
   pyenv install 3.10.17
   pyenv install 3.11.12
   pyenv install 3.12.10
   pyenv install 3.13.3
   pyenv global 3.13.3 3.12.10 3.11.12 3.10.17 3.9.22 3.8.20 3.7.17 2.7.18 system

Install test dependencies::

   pip install -r requirements_test.txt

After doing so, run the unit tests::

   tox

To limit tests to a particular python environment::

   tox -e py37

Run only linting tests::

   tox -e ruff

**nagiosplugin** also includes support for test coverage reports. Coverage
reports are updated automatically by `tox`. Open `htmlcov/index.html` to see
coverage reports.

You may run the supplied examples with the local interpreter::

   python3 nagiosplugin/examples/check_load.py


Documentation
-------------

The documentation depends on Sphinx.  The Sphinx configuration is tested against
the latest Python version supported by `nagiosplugin`.  If you are running a
different Python version in your virtual environment, you may need to update.
Install the necessary dependencies and then build the documentation::

   pip install -r requirements_docs.txt
   make docs

HTML documentation will be built and installed in `docs/_build/html/`.  You
can read the documentation by opening `docs/_build/html/index.html`.

Releasing
---------

This information will be unnecessary for most contributors.  It is only
relevant to those actually making releases.

Versioning
~~~~~~~~~~

**nagiosplugin** obeys the semantic version numbering specification
published on SemVer_, adapted slightly to be `PEP 440`_ compliant.

.. _SemVer: http://semver.org/
.. _PEP 440: https://www.python.org/dev/peps/pep-0440/


How to release
~~~~~~~~~~~~~~

Instructions below are for a hypothetical 0.1.2 release.  Make sure you use
the correct version numbers for your release, and don't copy and paste the
below examples.

Begin by making sure you have the build prerequisites installed::

   pip install -r requirements_build.txt

Create a release branch from `develop`::

   git checkout develop
   git checkout -b release/0.1.2

Check that all tests pass.  Apply hotfixes as necessary to pass all tests
before continuing.

Update the version number in `nagiosplugin/version.py`, and update the version
release date in the `HISTORY.txt` file::

   sed -i '' -e 's/\(__VERSION__ =\).*/\1 "0.1.2"/' nagiosplugin/version.py
   sed -i '' -e 's/0.1.2 (unreleased)/0.1.2 (2019-11-07)/' HISTORY.txt

You may need to update the `HISTORY.txt` file with additional changes.  You
can get a list of commits since the last release by generating a reverse log,
which you can edit down to just a list of relevant changes::

   git log --reverse --no-merges 0.1.1... > new-changes.txt

Do a test build of the distribution for the PyPi test site::

   python -m build

Check the contents of the packages in `dist/` to ensure they contain all of
the expected files.

Test your package prior to uploading::

   twine check dist/dist/nagiosplugin-0.1.2.tar.gz

Do a test upload with TestPyPi::

   twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Check on https://test.pypi.org/nagiosplugin that the package metadata looks
correct.  If everything is fine, proceed with the next steps.

Commit the updated history and version files, making sure both of the file
changes are in the same commit.  For a new version `0.1.2`::

   git stage HISTORY.txt nagiosplugin/version.py
   git commit -m "Preparing release 0.1.2"

Merge the release into the `main` branch and tag the release::

   git checkout main
   git merge release/0.1.2
   git tag 0.1.2
   git push
   git push --tags

Build the final **nagiosplugin** distribution for PyPi, and upload it::

   python -m build
   twine upload dist/*

Merge the release back into `develop` and then delete the release branch::

   git checkout develop
   git merge release/0.1.2
   git push
   git branch -d release/0.1.2

Go to https://readthedocs.io/ and ensure the new stable and dev releases are
available.


.. vim: set ft=rst sw=3 sts=3 et:
