Originally shared on Google Drive in 2022 - updated and moved to Confluence in May 2023 to reflect that we are no longer using Google Docs for specification documents.
Building Block Version Scheme & Release Process
...
Uniquely and semantically versioned
Developed iteratively with rapid releases
Fork-able into separate release flows and merged back (for localisedlocalized/contextualised contextualized versions)
Support Git workflowsSupport Google Docs workflows
Naming conventions
Naming conventions follow the following standard: <owner>-bb-<name>-<module>
In this document, we have been using specification as an explicit label of the Build Block specification.
Example of a GovStack Building Block Definition Document: govstack-bb-consent-management-definitionspecification
Example of a forked GovStack Building Block:gov.in-bb-consent-management-definitionspecification
Version schema
Building block definition documents have the following version 1.0.0 or X.Y.Z
...
Y = minor version, substantial changes based on feedback, changes with smaller side-effects, API changes required to be non-breaking.
Z = patch version, small changes, additions without side-effects, typos etc, may be released outside of a full review process
...
-draft1 = Draft release from WG
-poc1 = POC release, proof of concept, a release for Architecture WG Technical Committee or other BB WGs
-rc1 = Release candidate, a release pending input from review committee
...
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 artifact from their own Git branch, they may want to add the git commit hash or a timestamp, example: govstack-bb-consent-management-definitionspecification-1.2.3-git2be5010706654
Versioning of forks
...
Original GovStack version:
govstack-bb-consent-management-definitionspecification-1.0.0Forked version from gov.in, first release:
bb-consent-management-definitionspecification-gov.in-1.0.0-0.1
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
...
Specification lifecycle example (WIP)
The same project may have workflows in different systems, which thus have separate release cycles that are periodically synchronisedsynchronized.
For instance:
Workflow | Git | Comment | |
Definition doc draft | govstack-bb-consent- |
specification-1.0.0-draft1 |
Using the “draft” suffix, we tag versions in GitBook that are signed off by the WG. For instance to pass on for internal review. | |
Definition doc review release | govstack-bb-consent |
-specification-1.0.0-rc1 | Specification releases signed off by product owner. | ||
Definition doc review | govstack-bb-consent-specification-1.0.0 | Finally, we release a “stable” document without the draft/rc suffix. | |
Definition doc feedback processing | govstack-bb-consent- |
specification-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 |
Release Google Document to GitHub
govstack-bb-consent-management-definition-1.0.1
panelists. | |||
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:
Work Group members:
Google DriveGitBook: Releases versions with local suffix (drafts etc) or patch numbers
Git: Pull Requests from own forks
Work Group leads:
Google Drive: All releasesGitBook: Releases the “rc” label
Git: Pull Requests, potentially from WG common repository
Architecture groupProduct Owner / Technical Committee
Git/GitBook: All releases