todo.rst 9.96 KB
Newer Older
1
2
Todo
====
3

Antoine Beaupré's avatar
Antoine Beaupré committed
4
5
README improvements
-------------------
6

7
For now, I have only included here the :doc:`contribute` document, but
8
9
more should be added. There are a lot of templates around for
``README`` files which we could inspire from:
10
11
12
13
14
15
16
17
18
19
20
21
22
23

 * `the art of README <https://github.com/noffle/art-of-readme>`_ -
   has a nice checklist, from the `common-readme
   <https://github.com/noffle/common-readme>`_ node.js module guy
 * NPM has another `standard readme spec
   <https://www.npmjs.com/package/standard-readme-spec>`_
 * Perl has `standards
   <http://perldoc.perl.org/perlmodstyle.html#DOCUMENTING-YOUR-MODULE>`_,
   which are basically derived from manpages
 * manpages, themselves, have a standard set of headings, well
   described in the `mdoc(7) manpage
   <https://manpages.debian.org/mdoc>`_
 * Drupal has its own set of `guidelines for README files
   <https://www.drupal.org/docs/develop/documenting-your-project/readme-template>`_
Antoine Beaupré's avatar
Antoine Beaupré committed
24
 * yet another "kickass" `README template <https://dev.to/scottydocs/how-to-write-a-kickass-readme-5af9>`_
Antoine Beaupré's avatar
Antoine Beaupré committed
25
26
27
28
29
30
 * Ben Ford has an article named `Writing a great README
   <https://binford2k.com/2020/04/21/great-readme/>`_ which recommends
   the 5/30/90 rule: 5 seconds to decide if the README is worth a
   read, 30 seconds for the main pitch, 90 seconds for architecture,
   performance and more in-depth questions, then "the rest" (links to
   the rest of the docs, how to install, etc)
31
32
33
 * finally, this list wouldn't be complete without a `good discussion
   on stackoverflow
   <https://stackoverflow.com/questions/2304863/how-to-write-a-good-readme>`_
Antoine Beaupré's avatar
Antoine Beaupré committed
34

35
I did a quick review of the Art of README checklist, and we're not too
36
37
bad for a template. Ironically, I should review my own writing in the
`bug reporting blog post <https://anarc.at/blog/2016-10-14-bug-reporting/>`_.
38

Antoine Beaupré's avatar
Antoine Beaupré committed
39
40
41
I wonder if I should adopt the `Semantic Line Breaks standard
<https://sembr.org/>`_.

Antoine Beaupré's avatar
Antoine Beaupré committed
42
43
44
Changelog and index
-------------------

45
46
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
47
be a good addition as well.
48

Antoine Beaupré's avatar
Antoine Beaupré committed
49
50
Man pages
---------
51

52
53
54
55
56
57
58
59
60
61
There's also this whole thing about syncing the inline ``--help`` with
documentation and the manpage. There's `help2man
<https://www.gnu.org/software/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 :mod:`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.

62
63
64
65
66
67
68
69
70
See also my other projects (e.g. `monkeysign`_, `linkchecker`_,
`wallabako`_, `stressant`_, `debmans`_) for more examples of the
documentation layout.

 .. _monkeysign: https://monkeysphere.info/monkeysign
 .. _linkchecker: https://github.com/linkcheck/linkchecker
 .. _wallabako: https://gitlab.com/anarcat/wallabako/
 .. _stressant: https://gitlab.com/anarcat/stressant
 .. _debmans: http://debmans.readthedocs.io/
71

Antoine Beaupré's avatar
Antoine Beaupré committed
72
73
74
75
Commit messages
---------------

The contribution guidelines could benefit from improvements regarding
76
77
78
79
80
81
82
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
:doc:`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 :doc:`contribute` document, but
they could be expanded. Some documents I need to review:
Antoine Beaupré's avatar
Antoine Beaupré committed
83
84

 * `How to Write a Git Commit Message
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
   <https://chris.beams.io/posts/git-commit/>`_ - establishes "seven
   rules":
   
   1. Separate subject from body with a blank line
   2. Limit the subject line to 50 characters
   3. Capitalize the subject line
   4. Do not end the subject line with a period
   5. Use the imperative mood in the subject line
   6. Wrap the body at 72 characters
   7. Use the body to explain what and why vs. how

 * `Linux kernel's SubmittingPatches documentation
   <https://github.com/torvalds/linux/blob/master/Documentation/process/submitting-patches.rst#2-describe-your-changes>`_:

   * one patch should fix only one thing
   * describe the problem
   * describe the impact
   * quantify optimizations and tradeoffs (benchmarks!)
   * describe what is being done
   * use the imperative form (e.g. "make foo" instead of "this makes foo")
   * refer to bug reports, URL, emails if relevant
   * refer to a commit hash if the commit fixes a regression
   * if you refer to a commit, mention the SHA-1 and the short
     description

 * `ProGit commit guidelines
   <https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines>`_ -
   formatting tips and some of the above

Antoine Beaupré's avatar
Antoine Beaupré committed
114
115
116
117
 * `Romulo Oliveira's guide
   <https://github.com/RomuloOliveira/commit-messages-guide>`_ is also
   interesting

118
119
120
121
 * `A great commit message
   <https://fatbusinessman.com/2019/my-favourite-git-commit>`_ and
   `many more in this Hacker News discussion <https://news.ycombinator.com/item?id=21289827>`_

Antoine Beaupré's avatar
Antoine Beaupré committed
122
123
124
 * `Conventional commits <https://conventionalcommits.org/>`_ - a
   stricter approach?

Antoine Beaupré's avatar
Antoine Beaupré committed
125
126
127
128
 * `Patterns for writing better git commit messages
   <https://dev.to/helderburato/patterns-for-writing-better-git-commit-messages-4ba0>`_ -
   has good directives too

Antoine Beaupré's avatar
Antoine Beaupré committed
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
Funding
-------

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:

 * `review of funding approaches from Tyil
   <https://tyil.nl/articles/funding-yourself-as-free-software-developer.html>`_
 * `GitHub's Open Source funding guide
   <https://opensource.guide/getting-paid/>`_
 * Snowdrift has an excellent `market research
   <https://wiki.snowdrift.coop/market-research>`_ about all this,
   including payment gateways and crowdfunding platforms
 * `Other ideas from a random GitHub project
   <https://github.com/nayafia/lemonade-stand>`_
 * `License zero
   <https://writing.kemitchell.com/2017/09/12/The-License-Zero-Manifesto.html>`_
 * `Liberal Software <https://lwn.net/Articles/712376/>`_ and
   Percival's `paid support
   <http://www.daemonology.net/blog/2017-05-11-plan-for-foss-maintainers.html>`_
 * `GNOME apps funding <https://www.joaquimrocha.com/2017/09/05/paying-for-foss-apps/>`_

Whether any of this will be implemented in my projects remains an open
question, for which I am still looking `for feedback
<https://anarc.at/blog/2017-03-30-free-software-activities-march-2017/#looking-into-self-financing>`_. 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
<https://www.dailydot.com/layer8/patreon-antifa-altright-igd-lauren-southern/>`_... This
is a minefield.

166
167
168
169
170
171
172
173
174
175
176
Code
----

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
177
178
179
180
181
 5. type-checking (`mypy`_, `pyright`_, `feed2exec`_ uses the former)

.. _mypy: https://mypy.readthedocs.io/
.. _pyright: https://github.com/Microsoft/pyright
.. _feed2exec: https://feed2exec.readthedocs.io/
182
183
184
185
186
187
188
189
190
191
192

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 <https://github.com/un33k/python-slugify>`_ module - yet my
:func:`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.
Antoine Beaupré's avatar
Antoine Beaupré committed
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213

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 ``setup.py``, 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
Antoine Beaupré's avatar
Antoine Beaupré committed
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229

Finally, it looks like Python is moving away from ``setup.py`` to
build packages. Some tools have started using `pyproject.toml
<https://snarky.ca/what-the-heck-is-pyproject-toml/>`_ instead, like
`flit <https://flit.readthedocs.io/en/latest/>`_ and `poetry
<https://python-poetry.org/>`_. Unfortunately, neither supports
reading the version number from git: flit reads it from the package's
``__version__`` variable (`flit bug 257
<https://github.com/takluyver/flit/issues/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
<https://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files>`_
for the static ones (like trove classifiers) that do not need to be
present at runtime.