Originally shared on Google Drive

Building Block Version Scheme & Release Process

Objectives and requirements

GovStack Building Block Definition Documents and API specs must be:

  1. Uniquely and semantically versioned

  2. Developed iteratively with rapid releases

  3. Fork-able into separate release flows and merged back (for localised/contextualised versions)

  4. Support Git workflows

  5. Support Google Docs workflows

Naming conventions

Naming conventions follow the following standard: <owner>-bb-<name>-<module>

Example of a GovStack Building Block Definition Document:  govstack-bb-consent-definition

Example of a forked GovStack Building Block:gov.in-bb-consent-definition

Version schema

Building block definition documents have the following version 1.0.0 or X.Y.Z

Semantics:

X = major version, new features/requirements added, major changes to existing requirements, new review process required

Y = minor version, substantial changes based on feedback, changes with smaller side-effects

Z = patch version, small changes, additions without side-effects, typos etc, may be released outside of a full review process

Version suffixes

Version suffixes are used to release documents that have not finally been approved.

-draft1 = Draft release from WG
-poc1 = POC release, proof of concept, a release for Architecture WG or other BB WGs
-rc1 = Release candidate, a release pending input from review committee

Example using a version suffix to indicate that it is the first release candidate for TAC

Local version suffixes

A document can be versioned and released from a local source to clearly label draft status, experimental forks etc. For example if a WG member releases an artefact from their own Git branch, they may want to add the git commit hash or a timestamp, example: govstack-bb-consent-definition-1.2.3-git2be5010706654

Versioning of forks

A fork occurs when a Building Block has a temporary or permanent maintenance and release flow forked from its origin. It is important to understand which GovStack version that a fork originated from, we therefore propose that the fork maintains information about which upstream GovStack release it was last sync’ed with.

The label of the fork is technically not a part of the version, but a part of the name of the project.

Format: <upstream-version>-<fork-version>

Example:

The background of this version scheme can be understood from Debian Package versioning: https://manpages.debian.org/wheezy/dpkg-dev/deb-version.5.en.html  

Lifecycle example (WIP)

The same project may have workflows in different systems, which thus have separate release cycles that are periodically synchronised.

For instance:

Workflow

Google

Git

Comment

Definition doc draft

govstack-bb-consent-definition-gdocs-1.0.0-draft1

Here we can - if useful - tag versions in Google Doc with suffixes indicating a fortrunning draft number. So for instance, everytime a WG member signs off, they can cut out a version draft number.

Definition doc review

govstack-bb-consent-definition-gdocs-1.0.0

Finally, we release a “stable” document without the draft suffix.

Definition doc feedback processing

govstack-bb-consent-definition-gdocs-1.0.1

During a rapid processing of review feedback, we may wish to indicate updates by bumping the patch version each time, making the changes visible to review panellists.

Release Google Document to GitHub

govstack-bb-consent-definition-1.0.1

We continue the version number from Google Docs in order for backtracking to happen. But we remove“-gdocs” from the name.

Release for POC

This document will have SRS level detail with proven POC

Product level version

Same BB may be be used in different products, with different customization

Country level version

Same product may be used in different countries with different customization 

Release process (WIP)

It is noted that many people will have access to suggest changes, implement changes and tag versions. The following release process should be followed with respect to version numbering: