Add releasing instruction to CONTRIBUTING.md

Also add a RELEASE_NOTES template, so when releasing new versions is easy to clear the release notes by just copying the template. Signed-off-by: Leandro Lucarella <[email protected]>
frequenz-floss · Sep 23, 2022 · 94dc100 · 94dc100
1 parent d5b6f21
commit 94dc100
Show file tree

Hide file tree

Showing 2 changed files with 59 additions and 0 deletions.
diff --git a/.github/RELEASE_NOTES.template.md b/.github/RELEASE_NOTES.template.md
@@ -0,0 +1,17 @@
+# Frequenz Channels Release Notes
+
+## Summary
+
+<!-- Here goes a general summary of what this release is about -->
+
+## Upgrading
+
+<!-- Here goes notes on how to upgrade from previous versions, including if there are any depractions and what they should be replaced with --> 
+
+## New Features
+
+<!-- Here goes the main new features and examples or instructions on how to use them -->
+
+## Bug Fixes
+
+<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -28,3 +28,45 @@ You can also use `nox` to run the tests and other checks:
 python -m pip install nox
 nox
 ```
+
+Releasing
+=========
+
+These are the steps to create a new release:
+
+1. Get the latest head you want to create a release from.
+
+1. Update the `RELEASE_NOTES.md` file if it is not complete, up to date, and
+   clean from template comments (`<!-- ... ->`) and empty sections. Submit
+   a pull request if an update is needed, wait until it is merged, and update
+   the latest head you want to create a release from to get the new merged pull
+   request.
+
+3. Create a new signed tag using the release notes and
+   a [semver](https://semver.org/) compatible version number with a `v` prefix,
+   for example:
+
+   ```sh
+   git tag -s -F RELEASE_NOTES.md v0.0.1
+   ```
+
+4. Push the new tag.
+
+5. A GitHub action will test the tag and if all goes well it will create
+   a [GitHub
+   Release](https://github.com/frequenz-floss/frequenz-channels/releases),
+   create a new
+   [announcement](https://github.com/frequenz-floss/frequenz-channels/discussions/categories/announcements)
+   about the release, and upload a new package to
+   [PyPI](https://pypi.org/project/frequenz-channels/) automatically.
+
+6. Once this is done, reset the `RELEASE_NOTES.md` with the template:
+
+   ```sh
+   cp .github/RELEASE_NOTES.template.md RELEASE_NOTES.md
+   ```
+
+   Commit the new release notes and create a PR (this step should be automated
+   eventually too).
+
+7. Celebrate!