Upgrade release docs canary (#689)

* Canary documentation for starting release and how it works

* Explain versioning and how to tag

* Minor: better tag for beta promotion

* Add guideline for PR titles to PR template

* Review feedback

* Removed acronims as per feedback

.github/pull_request_template.md

@@ -1,3 +1,19 @@
+<!--
+Make sure that your PR title is clear and contains a traceability marker.
+
+Traceability Markers is what we use to understand the impact of your change at a glance.
+Pick one of the following:
+- Infra: Your change only includes documentation, comments, github actions or metabox
+- BugFix: Your change fixes a bug
+- New: Your chage is a new backward compatible feature, a new test/test plan/test inclusion
+- Breaking: Your change breaks backward compatibility.
+    - This includes any API change to checkbox-ng/checkbox-support
+    - Changes to PXU grammar/field requirements
+    - Breaking changes to dependencies in snaps (fwts upgrade for example)
+If your change is to providers it can only be (Infra, BugFix or New)
+
+Example Title: Fixed bugged behaviour of checkbox load config (Bugfix)
+-->
 ## Description
 
 <!--

tools/release/README.md

@@ -4,6 +4,46 @@
 Sometimes, the builders will be down and this might prevent building the
 packages.
 
+## When can you relase a new beta candidate
+
+You can release a new beta candidate when you have at least one commit tagged
+by the verification process. This process will add a tag to the latest commit
+it can fetch with the version that is being verified and a
+`edge-validation-success` suffix. Note, any commit with that suffix is in theory
+a valid candidate for promotion but please, if any more recent commit is marked
+as `edge-validation-failed` investigate why, we may have upgraded the testing
+infra from one commit to the other!
+
+The verification process works as follows:
+
+```mermaid
+flowchart TD
+    A[Wait for specific time of the day] --New changes--> D
+    D[Build runtime/frontend snaps]
+    A --No new change--> A
+    D --Build failed--> E(Tag commit with: edge-validation-failed)
+    E --> A
+    D --Build ok--> F[Verify snaps via Metabox]
+    F --Validation ok--> G[Run canary testing via jenkins]
+    F --Validation failed --->E
+    G --Validation failed --->E
+    G --Validation ok--->H(Tag commit with: edge-validation-success)
+```
+
+> **_NOTE:_** This process is fully automated, you don't need to trigger it.
+
+If you want to verify the status of the latest edge build, run:
+```bash
+$ git fetch --tags
+$ git describe --tags --match "*edge-validation*" origin/main &&
+    git log -1 $(
+        git describe --tags --match "*edge-validation*" --abbrev=0 origin/main)
+```
+
+These commands will show you the latest tag that is in the repo and the commit
+it is associated with. If this tag ends with `edge-validation-success` you can
+proceed with the release.
+
 ## Promote the previous beta release to stable
 
 Internal teams (mostly QA and Certification) are using the version in the beta
@@ -19,27 +59,55 @@ Then, it's time to build the new beta version.
 
 ## Tag the release
 
+First you need to understand what tag to push. Checkbox uses
+[semantic versioning], in order to calculate what version number you should
+push, you need to see what you are actually releasing.
+
+Run the following commands to get a list of changes since the last stable
+release:
+
+```bash
+$ git fetch --tags
+$ git describe --tags --match "*[0123456789]" origin/main &&
+    git log $(
+        git describe --tags --match "*[0123456789]" --abbrev=0 origin/main
+    )..origin/main
+```
+
+If the list includes:
+- Only bugfixes: you can use the version tag that was calculated by the
+`edge-verification` job (increment patch).
+- New, backward compatible features: you have to increment the minor version
+- Non-backward compatible changes: you have to increment the major version
+
+All commit messages in the main history should have a postfix indicating what
+kind of change they are:
+- **Infra:** are changes to our testing infrastructure, you can safely ignore
+them
+- **Bugfix:** are bugfixes, increment patch version
+- **New:** are new backward compatible features, increment minor version
+- **Breaking:** are new breaking changes, increment major version
+
+If you were to be at at the tag `v2.9.1-edge-validation-success` and you
+had to release a new version with at least one backward compatible new feature,
+run the following commands:
+
 - Clone the repository
   ```
-  git clone [email protected]:canonical/checkbox.git
+  $ git clone [email protected]:canonical/checkbox.git
   ```
 - Tag the release
   ```
-  git tag -s "v2.10.0" -m "Bump version: 2.9.1 → 2.10.0"
+  $ git tag -s "v2.10.0" -m "Beta promotion of: 2.9.1 → 2.10.0"
   ```
 - Push the tag to origin
   ```
-  git push --tags
+  $ git push --tags
   ```
-  > **_NOTE:_** Having to clone and not push the tag from an existing
-  workflow is actually a Github Action limitation[^1]:
-  > *if a workflow run pushes code using the repository's GITHUB_TOKEN, a new
-  workflow will not run even when the repository contains a workflow configured
-  to run when push events occur.*
 
 ## How packages versions are generated?
 
-Both Debian packages and checkbox snaps rely on [setuptools_scm] to extract 
+Both Debian packages and checkbox snaps rely on [setuptools_scm] to extract
 package versions from git metadata.
 
 ```
@@ -48,6 +116,15 @@ package versions from git metadata.
 '2.9.dev38+g896ae8978
 ```
 
+In general, when the HEAD of a branch is tagged, the version is going to be
+the tag. If a branch's HEAD is not tagged, the version is going to be the latest
+tag with the patch number incremented by 1, a postfix that encodes the distance
+from the tag itself (in the form of `dev{N}` where `N` is the number of
+commits since the latest tag) and the hash of the current HEAD.
+
+> **_NOTE_**: If you have some uncommitted changes your version might also have
+a date postfix in the form of `.YYYYMMDD`, this should never happen in a release!
+
 ## Monitor the build and publish workflows
 
 3 workflows are triggered on tag push events:
@@ -129,5 +206,6 @@ release
 [build]: https://github.com/canonical/checkbox/actions/runs/4371649401/jobs/7649877336
 [Draft Release Note]: https://github.com/canonical/checkbox/releases
 [mailing list page]: https://lists.ubuntu.com/mailman/listinfo/Checkbox-devel
+[semantic versioning]: https://semver.org
 
-[1]: https://lists.ubuntu.com/archives/checkbox-devel/2023-August/000508.html
+[1]: https://lists.ubuntu.com/archives/checkbox-devel/2023-August/000508.html