Documenting changes

The docs/changes directory of a Lino application contains:

  • one file per year (2019.rst, 2020.rst) with the change log.

  • optionally one file with release notes for each documented release

  • an index.rst file with a toctree directive.

change log

A document that lists the changes in a given application in chronological order.

release notes

A document that describes the changes in given version of a given application.

Writing change logs

Changes are grouped by date. Every new day gives a new heading.

There should never be more than one paragraph per change. Several related changes should be in a same paragraph. If a change deserves more documentation, this should be written in another place, and the change log should just link to this place.

Every release should be mentioned. If a release has release notes, we create a separate document and the change log will have a link to it.

Writing release notes

The application carrier decides for every release whether release notes should be written, and how detailed it should be. Some customers don't want us to write release notes, a simple email with a summary of the changes, written by the site maintainer, is enough for them.

Some releases are just a bugfix release, the change log is enough in that case because nobody wants to read a release notes page containing a single sentence.

Subheadings of a release notes document:

  • Overview. The minimum to be read by the site operator's responsible contact person.

  • Possible pitfalls. The first section to be read by the local support team after upgrading a production site.

  • Requested changes. Refer to the tickets that have been fixed or that have been worked on.

  • Changes that were not requested. For example changes caused by changes in third-party technologies. Optimizations introduced by other site operators.

  • Data migration notes. What has changed in the database schema.