1# Contributing
2
3The preferred way to report bugs about *diffoscope*, as well as suggest
4fixes and requests for improvements is to submit reports to the issue
5tracker at:
6
7    https://salsa.debian.org/reproducible-builds/diffoscope/issues
8
9You can also submit patches via *Merge Request* on Salsa, Debian's
10Gitlab instance. Start by forking the
11[`diffoscope` Git repository](https://salsa.debian.org/reproducible-builds/diffoscope)
12(see [documentation](https://salsa.debian.org/help/gitlab-basics/fork-project.md)),
13make your changes and commit them as you normally would. You can then push your
14changes and submit a *merge request* via Salsa. See:
15[Gitlab documentation](https://salsa.debian.org/help/gitlab-basics/add-merge-request.md)
16about *Merge Requests*.
17
18You can also submit bugs about Debian specific issues to the Debian bug
19tracker.
20
21## Testing
22
23diffoscope's test suite relies on [pytest](https://docs.pytest.org/);
24to run all tests use `pytest[-3]`, appending `-n 4` or similar to enable
25running tests concurrently. For faster interactive development here's
26an example of how to run a (much) smaller subset of tests:
27
28    $ pytest -v --exitfirst -k lib tests/comparators/test_elf.pyc [-pdb]
29
30More options are available at `[pytest -h]`.
31
32## Git setup
33
34diffoscope's codebase adheres to the output
35[Black](https://black.readthedocs.io/) source code reformatter. Since this was
36not always the case, the default output of `git-blame(1)` is not useful due to
37large changes made when it was adopted.
38
39As an optional step, you can ignore these commits using:
40
41    $ git config blame.ignoreRevsFile .git-blame-ignore-revs
42
43## Common development topics
44
45### Adding a comparator
46
47Diffoscope doesn't support a specific file type? Please contribute to
48the project! Each file type is handled by a comparator, and writing a
49new one is usually very easy. Here are the steps to add a new
50comparator:
51
52* Add the new comparator in `diffoscope/comparators`.
53
54* Declare the comparator File class in `ComparatorManager` in
55  `diffoscope/comparators/__init__.py`
56
57* Add a test under `tests/comparators/`
58
59* If required:
60
61  - Update the `Build-Depends` list in `debian/control` and regenerate
62    `debian/tests/control` by following the instructions in that file.
63
64  - Update the `EXTERNAL_TOOLS` list in
65   `diffoscope/external_tools.py`
66
67### Adding a new option
68
69Please try and refrain from adding new command-line options. A brief rationale
70may be found here:
71
72  https://salsa.debian.org/reproducible-builds/diffoscope/-/issues/18#note_183040
73
74
75## Release process
76
77### Uploading to Debian
78
79When uploading diffoscope to the Debian archive, please take extra care
80to make sure the uploaded source package is correct, that is it includes
81the files tests/data/test(1o) which in some cases are removed by
82dpkg-dev when building the package.
83
84See [#834315](https://bugs.debian.org/834315) for an example FTBFS bug
85caused by this. (See [#735377](https://bugs.debian.org/735377#44)
86and followups to learn how this happened and how to prevent it)
87
88### Signed tarballs
89
90Please also release a signed tarball:
91
92    $ VERSION=FIXME
93    $ git archive --format=tar --prefix=diffoscope-${VERSION}/ ${VERSION} | bzip2 -9 > diffoscope-${VERSION}.tar.bz2
94    $ gpg --detach-sig --armor --output=diffoscope-${VERSION}.tar.bz2.asc < diffoscope-${VERSION}.tar.bz2
95
96And commit them to our LFS repository at:
97
98    https://salsa.debian.org/reproducible-builds/reproducible-lfs
99
100### PyPI
101
102You can update the version on PyPI using:
103
104    $ python3 setup.py sdist upload --sign
105
106### Docker image
107
108Update the Docker image using:
109
110    $ docker build --force-rm --no-cache --pull -t registry.salsa.debian.org/reproducible-builds/diffoscope .
111    $ docker push registry.salsa.debian.org/reproducible-builds/diffoscope
112
113### Publicity
114
115To announce the package on the `diffoscope.org` homepage, use the `update`
116script in that repository.
117
118Once live entry appears, consider tweeting the release using the release from
119the `@reprobuilds` Twitter account.
120