CHANGELOG: add to reference (doc), add guidelines

Also fix a missing ADR link. Change-Id: Ia3a554e9ffea1e872a179baaac415e1d2365ba59
softwarefactory-project · Mar 6, 2024 · cf8fa2e · cf8fa2e
1 parent 13ae049
commit cf8fa2e
Show file tree

Hide file tree

Showing 5 changed files with 47 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,14 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
-## [master]
+## [in development]
 
 ### Added
 ### Changed
+### Deprecated
 ### Removed
 ### Fixed
+### Security
 
 ## [alpha] - not released
 
 - Initial alpha version. Please consult the commit log for detailed information.
-- From now all changes will be referenced into this changelog.
+- From now on all changes will be referenced into this changelog.
diff --git a/doc/developer/release.md b/doc/developer/release.md
@@ -1,14 +1,29 @@
-# How to release the sf-operator
+This page documents the release process of the SF operator.
 
-A CI job named [sf-operator-publish-olm-bundle-image](https://microshift.softwarefactory-project.io/zuul/t/local/builds?job_name=sf-operator-publish-olm-bundle-image&skip=0) runs in the `release` pipeline.
-The `release` pipeline is triggered when a git tag is created on the `sf-operator` repository.
-This job builds and pushes the following assets to Quay.io:
+# CHANGELOG Management
 
-- [A bundle image](https://quay.io/repository/software-factory/sf-operator-bundle?tab=tags)
-- [A catalog image](https://quay.io/repository/software-factory/sf-operator-catalog?tab=tags)
-- [An operator image](https://quay.io/repository/software-factory/sf-operator?tab=tags)
+We follow the guidelines of [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) to manage our CHANGELOG.
+
+Before tagging, please make sure the [CHANGELOG](../reference/CHANGELOG.md) is up to date:
+
+1. Rename the `[in development]` section to the next tag, followed by the UTC date as `YYYY-MM-DD` of the tag (for example `[v0.0.20] - 2023-12-31`)
+1. Remove any empty sections in the release block
+1. Prepend a template `[in development]` section like so:
+
+```markdown
+## [in development]
+
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security
+```
+
+Then commit the changes to the CHANGELOG for review, and have them validated and merged. **This change should be the last one before tagging.**
 
-## Tagging sf-operator
+# Tagging
 
 !!! note
     Only core contributors have the right to push a tag on the `sf-operator` repository.
@@ -18,6 +33,21 @@ This job builds and pushes the following assets to Quay.io:
 Here are the commands to run (assuming releasing HEAD to v0.0.20 version):
 
 ```sh
+git checkout master
+git pull origin master
 git tag v0.0.20 HEAD
 git push gerrit v0.0.20
 ```
+
+
+# Release Automation
+
+A CD job named [sf-operator-publish-olm-bundle-image](https://microshift.softwarefactory-project.io/zuul/t/local/builds?job_name=sf-operator-publish-olm-bundle-image&skip=0) runs in the `release` pipeline.
+The `release` pipeline is triggered when a git tag is created on the `sf-operator` repository.
+This job builds and pushes the following assets to Quay.io:
+
+- [A bundle image](https://quay.io/repository/software-factory/sf-operator-bundle?tab=tags)
+- [A catalog image](https://quay.io/repository/software-factory/sf-operator-catalog?tab=tags)
+- [An operator image](https://quay.io/repository/software-factory/sf-operator?tab=tags)
+
+Clusters where the operator is installed through OLM will upgrade automatically to the latest released version.
diff --git a/doc/reference/CHANGELOG.md b/doc/reference/CHANGELOG.md
@@ -0,0 +1 @@
+../../CHANGELOG.md
diff --git a/doc/reference/index.md b/doc/reference/index.md
@@ -9,4 +9,5 @@ This section contains links to references for the SF-Operator project.
 
 1. [API reference](./api/index.md)
 1. [CLI reference](./cli/index.md)
-1. [Architectural Decision Records](./adr/index.md)
+1. [Architectural Decision Records](./adr/index.md)
+1. [CHANGELOG](./CHANGELOG.md)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -118,9 +118,11 @@ nav:
       - reference/adr/0011-nodepool-builder.md
       - reference/adr/0012-CLI-overhaul.md
       - reference/adr/0013-more-CLI-features.md
+      - reference/adr/0014-external-zuul-executor.md
      # - Template: reference/adr/adr-template.md
     - Custom Resource Definitions: deployment/crds.md
     - API:
       - reference/api/index.md
     - CLI:
       - reference/cli/index.md
+    - CHANGELOG: reference/CHANGELOG.md