diff --git a/source/development/versioning.rst b/source/development/versioning.rst index 190cf93..4710b71 100644 --- a/source/development/versioning.rst +++ b/source/development/versioning.rst @@ -1,4 +1,77 @@ .. _versioning: -Versioning -========== +Releases and Versioning +======================= + +Bao Project's repositories 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 + thoroughly 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 amount 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. + +At any point during the release cycle **PATCH** version increments can be tagged to fix bugs, +especially safety hazards or security vulnerabilities. + +Release Announcement +-------------------- + +For each release bump major or minor versions, a release announcement should be redact containing +the most relevant modifications compared to the previous release. It must highlight new features as +well any interface modifications that require users to update their configurations and setups. + +The announcement must be publicized in the project's official communication channels (e.g., X, +LinkedIn, etc.); + +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; +* writing and publishing the release announcement; + +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. diff --git a/source/spelling_wordlist.txt b/source/spelling_wordlist.txt index c383579..868673c 100644 --- a/source/spelling_wordlist.txt +++ b/source/spelling_wordlist.txt @@ -67,3 +67,4 @@ subdirectory scalability codebase unix +incrementing