1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
|
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``.
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 ``pydoctor --docformat=google dulwich``
from the root of the repository, and then opening
``apidocs/index.html`` in your web browser.
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
Tests
~~~~~
Dulwich has two kinds of tests:
* Unit tests, which test individual functions and classes
* Compatibility tests, which test that Dulwich behaves in a way that is
compatible with C Git
The former should never invoke C Git, while the latter may do so. This is
to ensure that it is possible to run the unit tests in an environment
where C Git is not available.
Tests should not depend on the internet, or any other external services.
Avoid using mocks if at all possible; rather, design your code to be easily
testable without them. If you do need to use mocks, please use the
``unittest.mock`` module.
Running the tests
-----------------
To run the testsuite, you should be able to run ``dulwich.tests.test_suite``.
This will run the tests using unittest.
.. code:: console
$ python -m unittest dulwich.tests.test_suite
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
$ python -m unittest dulwich.tests.nocompat_test_suite
testr and tox configuration is also present.
Style and typing checks
-----------------------
Several static analysis tools are used to ensure code quality and consistency.
* Use ``ruff check`` to run all style-related checks.
* Use ``ruff format --check`` to check code formatting.
* Use ``mypy dulwich`` for typing checks.
* Use ``codespell`` to check for common misspellings.
Those checks are *mandatory*, a PR will not pass tests and will not be merged if
they aren't successful.
.. code:: console
$ ruff check
$ ruff format --check
$ mypy dulwich
$ codespell
In some cases you can automatically fix issues found by these tools. To do so, you can run:
.. code:: console
$ ruff check --fix # or pass --unsafe-fixes to apply more aggressive fixes
$ ruff format
$ codespell --config .codespellrc -w
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.
|
