doc/contributing.md

   1 # Contributing to pylibacl
   2
   3 Hi, and thanks for any and all contributions!
   4
   5 ## Bugs and patches
   6
   7 This is a small project, so let's keep things simple:
   8
   9 - Please file all bug reports on github
  10   (<https://github.com/iustin/pylibacl/issues>), as this allows
  11   archival and discovery by other people;
  12 - Send patches as pull requests; for larger changes, would be good to
  13   first open a bug to discuss the plans;
  14
  15 Due to simplicity, there are no old branches being kept alive, but if
  16 it ever happens that a bug is found in older versions and there is
  17 needed to support older Python versions, it is possible to do so.
  18
  19 ## Code standards
  20
  21 There are no formal standards, but:
  22
  23 - Code should be tested - this is why there's a [Codecov
  24   integration](https://app.codecov.io/gh/iustin/pylibacl/tree/main).
  25 - New functions should have good docstrings (in the C code).
  26 - New functions/constants should be listed in the documentation, see
  27   `doc/module.rst` for how to include them.
  28 - All non-trivial changes should be listed in `NEWS.md` for further
  29   inclusion in new releases documentation. Add an "unreleased" section
  30   (if one doesn't exist yet) to list the changes.
  31
  32 ## Release process
  33
  34 Right now, due to GPG signing, I'm doing releases and signing them
  35 manually (offline, I mean). Basically, once GitHub workflows are fine:
  36
  37 - Bump the version in all places - use `git grep -F $OLD_VER` and
  38   update as needed.
  39 - Ensure that `setup.py` has the right Python versions listed (bit me
  40   more than once).
  41 - Update the `NEWS.md` file is up to date (contents), and use the
  42   right date.
  43 - Check that the generated documentation (`make doc`) looks right.
  44
  45 Then run these steps:
  46
  47 ```
  48 $ make clean
  49 $ make distcheck # this leaves things in dist/
  50 $ git tag -m 'Release pylibacl-0.0.1' --sign v0.0.1
  51 $ gpg --sign -b -a dist/pylibacl-0.0.1.tar.gz
  52 $ python3 -m twine upload dist/*
  53 ```
  54
  55 Separately:
  56
  57 * Upload the `dist/` contents to GitHub and tag a new release.
  58 * Upload the `dist/` contents to the old-style download area,
  59   <https://pylibacl.k1024.org/downloads/>.
  60
  61 Hopefully one day all this can be more automated.
  62
  63 ## Signing key
  64
  65 The releases are currently signed by my key, see <https://k1024.org/contact/>.