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-definitionspecification
Example of a forked GovStack Building Block:gov.in-bb-consent-definitionspecification
Version schema
Building block definition documents have the following version 1.0.0 or X.Y.Z
...
-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-definitionspecification-1.2.3-git2be5010706654
Versioning of forks
...
Original GovStack version:
govstack-bb-consent-definitionspecification-1.0.0Forked version from gov.in, first release:
bb-consent-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-definition-gdocsspecification-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 numberUsing 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-definition-gdocsspecification-1.0.0 | Finally, we release a “stable” document without the draft/rc suffix. | |||
Definition doc feedback processing | govstack-bb-consent-definition-gdocsspecification-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 panellistspanelists. | |||
Release Google Document to GitHub |
| 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 |
...
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