dulwich/CONTRIBUTING.rst

All functionality should be available in pure Python. Optional Rust
implementations may be written for performance reasons, but should never
replace the Python implementation.

Where possible include updates to NEWS along with your improvements.

New functionality and bug fixes should be accompanied by matching unit tests.

Installing development dependencies
-----------------------------------

Contributing to Dulwich requires several more dependencies than are required to install
the base package; they are used to run tests and various other checks.

First, make sure your system has the Rust compiler and Cargo (the Rust package manager)
installed. As this is a system-level requirement and not a Python library, the right way
to install it depends on your platform. Please consult the `Rust documentation
<https://www.rust-lang.org/learn/get-started>`__ to find out more.

Next, you will need to set up your Python environment for Dulwich. An easy way to get
started is to install the checked out Dulwich package in editable mode with ``dev``
extras, preferably in a new virtual environment:

.. code:: console

   $ cd ~/path/to/checkouts/dulwich
   # Create and activate a virtual environment via your favourite method, such as pyenv,
   # uv, built-in venv module...
   $ python -m venv .venv && . .venv/bin/activate
   # Now install Dulwich and the required dependencies
   $ pip install -e ".[dev]"

This will ensure the tools needed to test your changes are installed. It is not necessary
to install Dulwich in editable mode (``-e``), but doing so is convenient for development,
as code changes will be visible immediately, without requiring a reinstall (although any
running Python processes will need to be reloaded to see the updated module
definitions). Editable mode only applies to Python code; if you modify any of the Rust
extension code, you will need to reinstall the package for the extensions to be
recompiled.

There are also other, optional dependencies which are needed to run the full test suite,
implement optional features, and provide the full typing information. They are however not
strictly necessary; the above is sufficient to start developing and have your PR pass the
tests in most cases. Please consult the ``[project.optional-dependencies]`` section in
``pyproject.toml`` and the various targets in ``Makefile`` for a full list of optional
dependencies.

Coding style
------------
The code follows the PEP8 coding style. There are ``ruff`` rules in place that define the
exact code style, please run it to make sure your changes are conformant. See also "Style
and typing checks" below for details on running style checkers.

Public methods, functions and classes should all have doc strings. Please use
Google style docstrings to document parameters and return values.
You can generate the documentation by running "make doc".

String Types
~~~~~~~~~~~~
Like Linux, Git treats filenames as arbitrary bytestrings. There is no prescribed
encoding for these strings, and although it is fairly common to use UTF-8, any
raw byte strings are supported.

For this reason, the lower levels in Dulwich treat git-based filenames as
bytestrings. It is up to the Dulwich API user to encode and decode them if
necessary. The porcelain may accept unicode strings and convert them to
bytestrings as necessary on the fly (using 'utf-8').

* on-disk filenames: regular strings, or ideally, pathlib.Path instances
* git-repository related filenames: bytes
* object sha1 digests (20 bytes long): bytes
* object sha1 hexdigests (40 bytes long): str (bytestrings on python2, strings
  on python3)

Exceptions
~~~~~~~~~~
When catching exceptions, please catch the specific exception type rather than
a more generic type (like OSError, IOError, Exception, etc.). This will
ensure that you do not accidentally catch unrelated exceptions.
The only exception is when you are reraising an exception, e.g. when
re-raising an exception after logging it.

Do not catch bare except, although ruff will warn you about this.

Keep the code within a try/except block as small as possible, so
that you do not accidentally catch unrelated exceptions.

Deprecating functionality
~~~~~~~~~~~~~~~~~~~~~~~~~
Dulwich uses the `dissolve` package to manage deprecations. If you want to deprecate
functionality, please use the `@replace_me` decorator from the root of the
dulwich package. This will ensure that the deprecation is handled correctly:

* It will be logged as a warning
* When the version of Dulwich is bumped, the deprecation will be removed
* Users can use `dissolve migrate` to automatically replace deprecated
  functionality in their code

Running the tests
-----------------
To run the testsuite, you should be able to simply run "make check". This
will run the tests using unittest.

.. code:: console

   $ make check

The compatibility tests that verify Dulwich behaves in a way that is compatible
with C Git are the slowest, so you may want to avoid them while developing:

.. code:: console

   $ make check-nocompat

testr and tox configuration is also present.

Style and typing checks
-----------------------

Use ``make all-style`` to run all style-related checks. Use ``make typing`` for typing
checks. Those checks are *mandatory*, a PR will not pass tests and will not be merged if
they aren't successful.

.. code:: console

   $ make all-style
   $ make typing

Some of these checks will modify the code to fix issues encountered, remember to commit
these changes afterwards!

There are also individual ``make`` targets to run just a single style check, see the
definition of ``all-style`` in ``Makefile``.

Merge requests
--------------
Please either send pull requests to the maintainer (jelmer@jelmer.uk) or create
new pull requests on GitHub.

Licensing
---------
All contributions should be made under the same license that Dulwich itself
comes under: both Apache License, version 2.0 or later and GNU General Public
License, version 2.0 or later.