Add document to describe release workflowdoc/release-workflow

Signed-off-by: Matthias Beyer <matthias.beyer@ifm.com>

1 files changed, 166 insertions, 0 deletions

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 <major version number> dot <minor version number> 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.
+