Versioning and Releases

[orcmid]

In all of the docEng materials and in all of the templates/skeletons/scaffolding, Semantic Versioning 2.0.0 is relied upon. This uses

major.minor,oatch_-optional-prerelease-identifier+optional-build-target-case

with restraints as specified for Semantic Versioning 2.

This applies to all the particles - components, individual text and markdown files, etc. That is particularly the case when any elements are incorporated from other sources, with appropriate links to the sources, whether customized or not.

Since bits and pieces are individually versioned and editable/customizable/cloned, how can one manage dependencies in what we will specify as releases? This is handled by GitHub release labeling.

A release of the main branch is accomplished by (1) branching to a release-identifying branch and (2) using the GitHub release identification mechanism to identify that branch as a release. This will set all of the dependencies, whether or not they have changed from previous releases. It will also make the specific dependencies known on examination of the associated branch. The precise procedure and constraints on it will be demonstrated and documented accordingly.

There are two important considerations for this

1. The main branch must be narrow enough to fit the scope of a single "document." We do not want to see materials and artifacts that are not dependencies in some release. This also pertains to the lifecycle tool chains as much as practical. We do want to capture enough that a release can be replicated as well as having an ability to analyze the dependencies.
2. Artifacts that correspond to forms/builds of a release are identified appropriately. Since these may be generated in some manner, there may need to be separation of the targets and the particular production. These do become part of the release identification of those artifacts and perhaps of the branch that they are derived in. This takes more consideration.

A significant consideration pertains to the document engineering and production being in the open and with multiple contributors in different capacities. The handling of commits to GitHub and incorporation of pull requests needs to be managed in a way that accommodates such participation.

The preserved versioning of independently modifiable components is important for identification of provenance and possible subsequent replacements when the particular artifacts are encountered apart from the GitHub (or other) repository. It is undesirable to rely on having/accessing the GitHub repository to learn essential versioning history. It is not always possible to embed sufficient annotation in the artifact itself. It then becomes important to name the artifact in a manner that supports clarity where the artifact is depended upon. This becomes a tedious case. Experimentation is required, including cases of artifact movement/renaming.

[orcmid]

There are some pattern collisions here, and I want to tease them out.

• Counterfeiting and Misappropriation. While not so serious as the counterfeiting of consumer software, there are certain countermeasures that may apply in the production of "official" document releases. These have to do with relabelling and packaging in a manner that implies some official character, including use of marks, covers, and links of various types, including ones for support or other services. There are a variety of countermeasures.

Withholding from the repository-in-the-open of the artifacts that are employed in a final production stage, such as the official cover, identifiers and notices, and links to the authentic origin of the document: everything that constitutes "branding" of the result and establishes it as an authoritative release. This works in the case of final stages that release an authenticated package.

Use of digital signatures that can be verified to confirm that the release is produced by the claimed authority and has not been altered. This works for document packages and other materials that can be "wrapped" in a manner that is difficult to corrupt without detection. This may require more expertise than one would like to have for confirming the authenticity and integrity of a release.

Such extreme arrangements are not always merited. They are applicable when there is a genuine hazard of counterfeits appearing on eBay and other outlets individually or as part of compilations intended to introduce adware or even malware into the computers of customers, as has been done persistently with bundled/repackaged Apache OpenOffice releases.

• that's an unlikely concern. Intersecting patterns are next in this enumeration.

• Umm, interruption. I have edited more items for the enumeration here only to lose the work. I forget that Issues and Discussion are not workable off-line and incorporated in the GitHub project with the same facility as the code. I also forget that I do have a way to edit markdown off-line and then paste the result into an Issue or Discussion post or comment. I need to look into how that is reflected in a GitHub-housed document engineering effort.