How To Contribute
=================

Reporting Bugs
--------------

- Try to include a reproducible example.
- Include which versions of devpi packages you use and whether you use any plugins.


Pull Requests
-------------

- Submit Pull Requests against the ``main`` branch.
- Provide a good description of what you're doing and why.
- Provide tests that cover your changes and try to run the tests locally first.
- If you are unsure on how to write a test, please ask and we will point you to
  existing tests which should help you writing new ones.
- Embrace ``git rebase`` to create "nice" commits and history.
- We strive for PEP8 compliance.
  New code must comply and there are lint-tests in CI using flake8 and ruff.
  Old code must only comply when it's changed.
  No large unnecessary cleanups which would only make the PR harder to read.
- Add a changelog entry in the ``news`` folder of touched packages as a new file.
  The filename should end with the type of the change as in: ``removal``, ``feature`` or ``bugfix``
  Try to follow the style of existing entries.
  The leading dash will be generated by towncrier.
  You can test the output with ``towncrier --draft``.


Running tests
-------------

Use `UV <https://docs.astral.sh/uv>`_ or another tool to create a virtualenv.
Activate the virtualenv for devpi and use the ``dev-bootstrap.sh`` script to
install Python packages needed for development and testing.

Run ``pytest <packagename>`` to run the tests of the package (client, common,
server, web etc) you are working on.

If you can, run ``tox`` in the directory of the changed packages to cover
different Python versions before making a PR.


Automated Testing
-----------------

Every PR is automatically tested and the status will be visible on the PR once
the tests ran.


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

Devpi's documentation uses the `Sphinx <https://www.sphinx-doc.org>`_
documentation system, which in turn is based on `docutils <http://docutils.sourceforge.net/>`_.
The basic idea is that lightly-formatted plain-text documentation is
transformed into HTML, PDF, and any other output format.

To build the documentation locally, perform the following steps from the
``doc`` directory with the virtualenv activated::

$ make html

To get started contributing, you’ll want to read the `reStructuredText reference <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html#rst-index>`_.

To regenerate the command line examples run the following::

$ PIP_INDEX_URL=https://pypi.org/simple/ make regen

That uses the official releases.
If you want to use unreleased versions,
use a custom index on a devpi server.
