From 457cc69082ea5091b0cc0a1dfc3cc5db97f37458 Mon Sep 17 00:00:00 2001 From: Jose Martins Date: Fri, 27 Oct 2023 13:53:08 +0100 Subject: [PATCH] feat(dev): add release and versioning guidelines Signed-off-by: Jose Martins --- source/development/versioning.rst | 67 ++++++++++++++++++++++++++++++- 1 file changed, 65 insertions(+), 2 deletions(-) diff --git a/source/development/versioning.rst b/source/development/versioning.rst index 190cf93..93ec544 100644 --- a/source/development/versioning.rst +++ b/source/development/versioning.rst @@ -1,4 +1,67 @@ .. _versioning: -Versioning -========== +Releases and Versioning +====================== + +Bao Project's repos follow a `semantic versioning scheme `_ where, for each +release, the specific `git commit is tagged ` +with a label with the form MAJOR.MINOR.PATCH, where each version component is incremented as +following: + +* **MAJOR** version when you make incompatible API changes +* **MINOR** version when you add functionality in a backward compatible manner +* **PATCH** version when you make backward compatible bug fixes + +When incrementing a given version, the lower order components must be set to 0. + +To illustrate, a project in its `2.3.1` version might: + +* bump to `2.3.2` if a given bug is patched; +* go to `2.4.0` when adding new features that don't break interface compatibility; +* tag `3.0.0` when adding new features that break interface compatibility; + +Release Cycle +------------- + +Bao's Project releases follow a loosely time-based cycle. The expected release cadence, +specifically, bumping the **MINOR** or **MAJOR** versions, is expected to be every 4 to 8 months, +depending on the number of contributions on that given period. That is, if the number of +contributions does not justify a release bump, the release can be postponed to a maximum of 8 +months. + +Each release cycle is essentially composed by two stages: + +* the **development stage**, where the normal development process goes on, PRs with either new + features, fixes or other are submitted, reviewed and merged asynchronously, following the + :ref:`contribution guidelines `. + +* during **stabilization stage**, the contributions made during the development stage should be + thorougly tested with the most comprehensive test batteries available. Further, integration tests + may be added at this point. Besides new tests, maintainers must stop accepting PRs that are not + bug fixes or documentation. This stage is expected to last between 2 to 8 weeks, so maintainers + should be aware to stop the development stage after a maximum of about 6 months depending on the + ammount of new contributions. More contributions will require a longer pre-release stage. + +At the end of the release cycle the version is tagged and the process starts all over again.s + +At any point during the release cycle **PATCH** version increments can be tagged to fix bugs, +especially safety hazards or security vulnerabilities. + + +Release Manager +--------------- + +For each release cycle one of the repo's maintainers (ideally always the same), should be elected +the **release manager**, which will be responsible for: + +* deciding when the stabilization stage begins and ends; +* coordinating other maintainers during the stabilization phase; +* tagging and pushing the version to the repo; + + +Submodule Management +-------------------- + +Upon a release tagging, each submodule in the repo should be pointing to a specific release of the +submodule's repo. This may require that a repository's release cycle to be somewhat synchronized to +the release cycle of its submodule dependencies.