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