From cf8fa2ea2092b0f34cf7fd223358106c5cb5813f Mon Sep 17 00:00:00 2001 From: Matthieu Huin Date: Wed, 6 Mar 2024 16:31:58 +0100 Subject: [PATCH] CHANGELOG: add to reference (doc), add guidelines Also fix a missing ADR link. Change-Id: Ia3a554e9ffea1e872a179baaac415e1d2365ba59 --- CHANGELOG.md | 6 +++-- doc/developer/release.md | 46 +++++++++++++++++++++++++++++++------- doc/reference/CHANGELOG.md | 1 + doc/reference/index.md | 3 ++- mkdocs.yml | 2 ++ 5 files changed, 47 insertions(+), 11 deletions(-) create mode 120000 doc/reference/CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 3bd58d60..d02306fd 100644 --- 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 index b19661e5..68e98406 100644 --- 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. \ No newline at end of file diff --git a/doc/reference/CHANGELOG.md b/doc/reference/CHANGELOG.md new file mode 120000 index 00000000..699cc9e7 --- /dev/null +++ b/doc/reference/CHANGELOG.md @@ -0,0 +1 @@ +../../CHANGELOG.md \ No newline at end of file diff --git a/doc/reference/index.md b/doc/reference/index.md index a9464d1d..1964f80e 100644 --- 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) \ No newline at end of file +1. [Architectural Decision Records](./adr/index.md) +1. [CHANGELOG](./CHANGELOG.md) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index cbf3d372..4adadab7 100644 --- 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