Wednesday, February 27, 2019¶
Hamza started to do application development for Mathieu. This is a historic step for Lino as it is the first time that somebody other than me talks directly with a customer (and then implements the code changes).
This raised some questions about how to organize the documentation of our
work? At least the release notes and French docs for welcht are to be
maintained by Hamza They are currently in
manuals/welfare_fr, which is
rather disturbing. We started a new page of change notes for Welfare
And –what a coincidence!– at the same time a developer Marc Fargas from Spain (I don’t know him yet) tried to install Lino Welfare and posted an issue on GitHub. I fixed this issue and wrote installation instructions for Marc.
We could move
manuals/welfare_fr to the welfare repo into a folder
manuals/welfare_de should go to
This would be a solution at the moment, but imagine we get a third Lino Welfare customer. They would probably want their own variant (i.e. another application). Let’s say Sankt Vith. They will want release notes in German. And their release notes will be different from those for weleup.
It might sound like overkill at the moment, but I currently believe that we do
need two new repositories and Python packages
lino_welfare would contain only the shared code
for all Welfare applications. It would be a kind of “extended extension library”
About the difference between release notes and change notes.
Release notes are written for the customer, in the language of the customer,
and there is one page for every new version. A new version can mean months of
work and many changes. Release notes are stored in a file
docs/changes/X.Y.Z.rst. We currently use date-based (not semantic)
versioning because there is no roadmap.
Change notes are written for the developers, in English, and there is one page
per year. Every commit should have at least two changed files: the source code
and a sentence in
docs/changes/yyyy.rst. Change notes are a bit
redundant with commit messages. But they have some advantages: You can modify
them later, e.g. when it turns out that a formulation was misleading. They can
use Sphinx reference system to link to the user manual or the specs. They can
summarize a series of commits.
Applications (weleup, welcht, cosi, tera…) have release notes, but libraries (atelier, lino, xl, welfare) have just change notes. Because the latter is less work, and because there is currently nobody except ourselves who would want to discuss about individual library releases.