From 9cae442645ead2419d259df6bd576eb4c638ac3b Mon Sep 17 00:00:00 2001 From: Matthias Beyer Date: Fri, 15 Jul 2022 10:09:58 +0200 Subject: Add document to describe release workflow Signed-off-by: Matthias Beyer --- docs/src/release-workflow.md | 166 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 docs/src/release-workflow.md diff --git a/docs/src/release-workflow.md b/docs/src/release-workflow.md new file mode 100644 index 00000000..f702d88e --- /dev/null +++ b/docs/src/release-workflow.md @@ -0,0 +1,166 @@ +# Release workflow + +The following describes how thin-edge.io is released. + +We adhere to [semver](https://semver.org). + +## Preface + +The following document describes the release process of the thin-edge.io project +and the corrosponding crates. + +There are many ways software projects can be published. In small projects, +releasing off of the `main` branch might suffice. Larger projects tend to +implement a dedicated strategy for their release workflow. + +As thin-edge.io wants to become a project of potentially many individuals and +contributing parties, we implement a dedicated release workflow as well. + +The goal of the workflow described in this document is to have _as little impact +as possible_ on the general development of the project. +Releases should _never_ stop, prevent or even just slow down the normal +development of the project. +For example, halting development on the `main` branch and forbidding +contributors and maintainers to merge changes to it even for as little as one +hour just so we can publish a new release is not acceptable. +Also should "patch" releases (sometimes called "bugfix releases") have no impact +on the project pace or even concern developers - they should just happen in +parallel without any influence on the normal development activities. + +Because of this requirement, we implement the following workflow. + +## Release cycle + +Minor releases are published roughly every 3 months. + +Until a minor release is published, the previous minor release _can_ receive +patch releases. These patch releases _only_ contain bugfixes (accordingly to +[semver](https://semver.org/)) and never contain new functionality. + +## Strategy + +We use the release-branch strategy, where development happens on the `main` +branch and releases are done on dedicated `release-X.Y.Z` branches. + +Because we employ the "evergreen main branch" strategy and all of our merge +commits on the `main` branch are guaranteed to successfully build and pass CI, a +release can be made starting from every commit on the `main` branch. + +**Note:** There is no description for major releases yet, as we haven't decided +on a process for major releases yet. + +## Release maintainer + +For every release, one or more "release maintainers" are appointed. These +maintainers have to be in the "release-maintainers" team. + +Multiple release maintainers should be prefered, to prevent release delay due to +vacation, sickness or similar things. + +The release maintainers take care of the branch-off of the `main` branch, the +actual release as well as applying backports of bugfixes to the release branch +and subsequent patch-level releases. + +Backport pull requests might still be opened by anyone, but the release +maintainer(s) decide when and how to apply them to the release branch. + +## Release branches + +Release branches MUST be named with a pattern. This pattern is + +``` +"release" dash dot dot "x" +``` + +The `"x"` is used instead of the "patch version number", because patch releases +are published from the release branches (read below). + +A release branch gets the following rules enforced via GitHub: + +* Only the "release-maintainers" team can create branches named `"release-*"` +* Pull requests are required on these branches +* Status checks are required to succeed on these branches +* "CODEOWNERS" is **not** enforced on these branches +* These rules are also enforced for administrators + +## Minor releases + +The following steps happen when a minor release is made: + +1. One release maintainer creates a branch, starting from a recent commit on + `main`, named `release-MAJOR.MINOR.x` , where `MAJOR` and `MINOR` are the + respective numbers, followed by a "x" in the `PATCH`-version-number-position +2. It is ensured that this branch cannot be pushed to by anyone except the + "bors" merge bot +3. The release maintainer crafts the `CHANGELOG.md` entries for this release and + opens a pull request for it, targeting the aforementioned release branch. + They might take patches from others to fill said `CHANGELOG.md` +4. Once agreed upon with everyone involved, they merge the PR for the + `CHANGELOG.md` to the release branch +5. The release maintainer publishes the release on crates.io and creates a new + tag for the release using `git tag -a vMAJOR.MINOR.0`. + They might add a tag message as they seem appropriate. + They then push the tag to the GitHub repository of the project +6. After the release is done, the `CHANGELOG.md` changes are cherry-picked to a + PR for the `main` branch by the release maintainer +7. After the release is done, the release maintainer opens a pull request to the + `main` branch to update all version numbers of all crates to the next minor + version + +## Patch releases + +Patch releases are published when appropriate, there is no fixed release cycle. +It might be a good rule-of-thumb to not release more than one patch release per +week. + +### Backporting + +Bugfixes that are added to a patch release _must_ have been applied to the +`main` branch, before they are backported to the appropriate `release-x.y.z` +branch. +If a bugfix that is applied to `main` cannot be backported, due to either +conflicts or because the feature that is about to be fixed does not exist in the +`release-x.y.z` branch anymore, the patch may be adapted to apply cleanly or a +special patch may be crafted. + +In any case, fixes that are backported to a `release-x.y.z` branch, MUST pass +CI and thus MUST be submitted to the release branch via a pull request. + +### Publishing of patch releases + +A patch release is published as soon as the release maintainer thinks it is +appropriate. + +The steps the release maintainer follows are almost the same as the steps of the +minor release workflow: + +* The release maintainer submits a pull request to the release branch with the + following changes: + * `CHANEGLOG.md` entries for the patch level release + * Updates of the version numbers for all crates in the "patch"-level position, + e.g. "0.42.0" becomes "0.42.1", +* Once the aforementioned pull request is merged, the release maintainer + publishes the release on crates.io, tags (`git tag -a vMAJOR.MINOR.PATCH`) + the release and pushes the tag to the GitHub repository of the project +* Once the release is published, the release maintainer opens a pull request to + the `main` branch of the project, porting the changes that were made to the + `CHANGELOG.md` file to this branch + +## More + +The `CHANGELOG.md` is added on the release branch rather than on the `main` +branch. The reason for this is the workflow: If the changelog is adapted on +`main`, the branchoff for the release branch can _only_ happen directly after +the changelog was merged, because other merges may introduce new changes that +need to be in the changelog. Also, the changelog-adding pull request must be up +to date all the time. +If the changelog is added on the release branch, no synchronization is +necessary. +Instead, the changelog entries can be "backported" to `main`, which is trivial. + +In a similar fashion are patch-level `CHANGELOG.md` entries ported to the `main` +branch. + +The `main` branch does never see changes to the version strings of the crates in +the "patch" level position. This is intentional, as there is no need for that. + -- cgit v1.2.3