Modular docs should have versioned releases

[rolfedh]

Organizations such as Red Hat use modular docs as a standard. Without versioned releases of mod docs, it is very difficult to track what changed from one point in time to another. This difficulty tracking and responding to individual changes causes fatigue and opposition to changes among the groups that apply this standard. It makes defining "what's Done" impossible. It may also impact efforts to create tooling. To avoid these types of problems and improve adoption, most standards apply change control methods such as versioned releases.

[rolfedh]

During this month's (February) Steering Group meeting, members spoke in favor of marking templates with a date or a version number. I proposed versioning and version numbers as a way to overcome writer frustration with incremental changes. The group supported applying version numbers to the templates.

[jhradilek]

I would suggest adopting similar approach to Ubuntu for versioning and including a code for the origin of the template too. So for a template published on January 28, 2021 and generated by newdoc, something like the following:

// ver: 21.01.28-nd

I would also recommend placing it to a predictable place near the top of the template, perhaps even on the first line.

[jhradilek]

To explain my reasoning a little: without further documentation in the form of a ChangeLog, the traditional version number holds very little information on its own. By adopting a versioning scheme similar to what I am suggesting, we would maximize the usefulness of having a version in the template.

[thatdocslady]

This seems good if there's a way to automate it somehow. Maybe we can leverage the GH changelog and have a link to it from the top of the templates, so that we won't need to manually change the date with every push. Not sure how easy it is to automate the changelog so the point might be moot ;)

[emmurphy1]

This issue was discussed again in the March 8, 2023 Steering Committee meeting. @mjahoda suggested that there might be a solution through GitHub actions and he will look into it.

[rolfedh]

@mjahoda suggested that there might be a solution through GitHub actions and he will look into it.

@mjahoda, did you find a potential solution?

[mjahoda]

@rolfedh I found out Github actions supports for example getting time for timestamping, but I don't have any practical experience with this automation framework.

[mjahoda]

We've just discussed possible automated solutions through Github actions with @VladimirSlavik.

The bottom line is that modifying source files in the repository is so complicated and the cadence of changes is so low that we would recommend to add (and update) version stamps manually.

[rolfedh]

Thanks for looking into this @mjahoda. I'll bring this recommendation to the mod docs council.

[jhradilek]

Looking back at this after full three years, as one of the people who advocated for this feature I really do not think that focusing overly on automatic versioning is in the best spirit of the original intent. I think we all agree that we do not need to be notified every time a typo is fixed or something is better explained in the numerous comment blocks. Looking back at what changed in the template over the past three years, I can see a handful of updates that would have benefited from being versioned, something that even done manually would have taken less effort than setting up automation for it.

On August 1, this group merged a change that altered the way modules are internally identified, making previously documented :_content-type: obsolete and replacing it with :_mod-docs-content-type:. This was a significant change that had impact on the entire documentation team, yet went largely unnoticed (and undocumented). In fact, newdoc, the tool that majority of writers use to manage templates, only implemented the updated template several months later, on September 29. I only noticed because independently, I was working on the script that uses these attributes and noticed the discrepancy.

I don't think the point of versioning the templates is to track every minor change. I do think that having this type of change reflected in a new version would:

• make it easier to detect the templates used by writers after this change are outdated
• make it easier to detect which files need updating without having to guess based on the content of said files
• make it a conscious decision that should be accompanied with review of the documentation
• make it easier to communicate these changes to the wider group.

[jhradilek]

For reference, to semi-automate the version updates, you can add a simple script or even a Makefile to the root directory of the project, for example:

# A custom makefile for the modular-docs repository
# Copyright (C) 2023 Jaromir Hradilek

# General settings:
SHELL     = /bin/sh

# Source files and directories:
SRCSDIR   = modular-docs-manual/files
SRCS     := $(wildcard $(SRCSDIR)/TEMPLATE_*.adoc)

# Helper functions:
bump      = $(foreach file, $(SRCS), $(shell \sed -i 's/^\(:_mod-docs-version:[ \t]\+\)\([0-9]\+\)\.\([0-9]\+\)\.\([0-9]\+\)/echo "\1$$((\2+$(1))).$$((\3+$(2))).$$((\4+$(3)))"/e' $(file)))

.PHONY: bump_patch
bump_patch:
    @echo "Incrementing the patch version in template files..."
    $(call bump,0,0,1)
    @echo "Done."

.PHONY: bump_minor
bump_minor:
    @echo "Incrementing the minor version in template files..."
    $(call bump,0,1,0)
    @echo "Done."

.PHONY: bump_major
bump_major:
    @echo "Incrementing the major version in template files..."
    $(call bump,1,0,0)
    @echo "Done."

This Makefile assumes that your template has the following line in it (the number does not matter, the format does):

:_mod-docs-version: 2.1.3

To update the patch version from 2.1.3 to 2.1.4 in all template files, you could then run:

$ make bump_patch
Incrementing the patch version in template files...
Done.

I like makefiles as the bash completion for subcommands works with no additional effort, they are standard part of projects, and there are templates for GitHub workflows that use them for packaging releases, for example. Note that the above was tested on Linux with GNU make and GNU sed.

[rolfedh]

Based on the conversation above, we agreed in one of our recent meeting to have release notes for significant changes. We didn't define what might contitute a release thought. One solution might be to adopt the the approach used in the IBM Style Guide's "What's new" section:

• It relies on a clear, simple, chronology of significant changes.
• It lists only significant changes, providing a summary and a convenient link.