README improvements

For now, I have only included here the Contribution guide document, but more should be added. There are a lot of templates around for README files which we could inspire from:

I did a quick review of the Art of README checklist, and we’re not too bad for a template. Ironically, I should review my own writing in the bug reporting blog post.

Changelog and index

The index.rst file should link to a template design document as well, along with an example of how to build a manpage. A changelog may be a good addition as well.

Man pages

There’s also this whole thing about syncing the inline --help with documentation and the manpage. There’s help2man that can be useful for simpler programs, and I have used it to bootstrap the manpage for undertime (I think). Otherwise, there’s a whole slew of half-broken stuff to turn argparse output directly into a manpage in the build system. This is how Monkeysign works. Finally, what I actually prefer (and I do in stressant) is to write the manpage by hand, in RST, and convert it to a manpage at build time.

See also my other projects (e.g. monkeysign, linkchecker, wallabako, stressant, debmans) for more examples of the documentation layout.

Commit messages

The contribution guidelines could benefit from improvements regarding commit messages. People often write fairly bad commit messages in patches and commits on projects I participate in. It’s also the case with bug reports, but we have fairly good instructions in the Support template here. Patches are specifically painful as there are no templates that can force users to do the right thing. There are some notes in the Contribution guide document, but they could be expanded. Some documents I need to review:


Another thing I’m looking at is donations for financing software projects. I don’t like donations too much because that is charity-based, which skews social dynamics away from the republic and towards capital, but that’s another political discussion that cannot be resolved in the short term. We still need to find ways of feeding developers and the options are rare. Here are a few reviews worth mentioning:

Whether any of this will be implemented in my projects remains an open question, for which I am still looking for feedback. One of the concerns is that launching a funding campaign that eventually fails could have a net negative reputation and psychological impacts. Furthermore, we may want to avoid supporting certain platforms that ban political speech… This is a minefield.


I still don’t know what to do with that code. Let loose, this could become like Stackoverflow: a huge dump of random code. Ideally, the following steps should be taken:

  1. 100% documentation coverage
  2. 100% test coverage
  3. parts or everything published as (a?) module(s?)
  4. parts or everything merged in the standard library

Stuff like the logging handlers, in particular, should especially be considered for merging. On the other hand, I also like the idea of simply copy-pasting small bits of code as needed. There is already a slugify module - yet my ecdysis.slug() function is still useful because it’s much simpler and it’s a one-liner that can be copy-pasted in your code without adding another dependency…

Note that code is nevertheless split up in modules that match the upstream module names where they could possibly end up, when relevant.

There are other code snippets that are not included here yet, because I’m not sure they’re good enough or that I would actually reuse them:

  • for pid files, I wrote my own PidFile class in bup-cron, but should look at lockfile
  • to run commands, stressant has this useful collectCmd function to collect output of running commands. bup-cron also has shit like that.
  • for, monkeysign has things to generate manpages (I used Sphinx instead in stressant), automatically call sphinx from the build chain, and translation stuff. debmans also has a neat __main__ hook. openstack’s pbr project may be relevant here as well.
  • monkeysign also has a UI abstraction layer that well… works more or less well, but at least works.
  • gameclock also has some neat ideas that may be reused

Finally, it looks like Python is moving away from to build packages. Some tools have started using pyproject.toml instead, like flit and poetry. Unfortunately, neither supports reading the version number from git: flit reads it from the package’s __version__ variable (flit bug 257) and poetry hardcodes it in the pyproject.toml file, neither of which seem like the right solution as it duplicates information from the source of truth: git. So I’m still using setuptools, but I should probably consider moving the metadata to setup.cfg for the static ones (like trove classifiers) that do not need to be present at runtime.