docs(readme): add release engineering instructions

Author: niheconomoum

README.md

@@ -1,16 +1,14 @@
-# https://github.com/IdentityPython/satosa-docker
+# satosa-docker
 
-## Maintained by: [the Identity Python project](https://github.com/IdentityPython/satosa-docker)
+This is the source repository of the [Docker "Official Image"](https://github.com/docker-library/official-images#what-are-official-images) for [`satosa`](https://hub.docker.com/_/satosa/).
 
-This is the Git repo of the [Docker "Official Image"](https://github.com/docker-library/official-images#what-are-official-images) for [`satosa`](https://hub.docker.com/_/satosa/). See [the Docker Hub page](https://hub.docker.com/_/satosa/) for the full readme on how to use this Docker image and for information regarding contributing and issues.
+The image description on Docker Hub is generated from [the docker-library/docs repository](https://github.com/docker-library/docs), specifically [the `satosa` directory](https://github.com/docker-library/docs/tree/master/satosa).
 
-The [full image description on Docker Hub](https://hub.docker.com/_/satosa/) is generated/maintained over in [the docker-library/docs repository](https://github.com/docker-library/docs), specifically in [the `satosa` directory](https://github.com/docker-library/docs/tree/master/satosa).
+## See a change merged here that hasn't shown up on Docker Hub?
 
-## See a change merged here that doesn't show up on Docker Hub yet?
+For more information about the Docker "Official Images" change lifecycle, see [the "An image's source changed in Git, now what?" FAQ entry](https://github.com/docker-library/faq#an-images-source-changed-in-git-now-what).
 
-For more information about the full official images change lifecycle, see [the "An image's source changed in Git, now what?" FAQ entry](https://github.com/docker-library/faq#an-images-source-changed-in-git-now-what).
-
-For outstanding `satosa` image PRs, check [PRs with the "library/satosa" label on the official-images repository](https://github.com/docker-library/official-images/labels/library%2Fsatosa). For the current "source of truth" for [`satosa`](https://hub.docker.com/_/satosa/), see [the `library/satosa` file in the official-images repository](https://github.com/docker-library/official-images/blob/master/library/satosa).
+For outstanding `satosa` image PRs, check [PRs with the "library/satosa" label on the official-images repository](https://github.com/docker-library/official-images/labels/library%2Fsatosa). For the current "source of truth" for the `satosa` image, see [the `library/satosa` file in the official-images repository](https://github.com/docker-library/official-images/blob/master/library/satosa).
 
 ---
 
@@ -22,4 +20,62 @@ For outstanding `satosa` image PRs, check [PRs with the "library/satosa" label o
 | [![arm64v8 build status badge](https://img.shields.io/jenkins/s/https/doi-janky.infosiftr.net/job/multiarch/job/arm64v8/job/satosa.svg?label=arm64v8)](https://doi-janky.infosiftr.net/job/multiarch/job/arm64v8/job/satosa/) | [![i386 build status badge](https://img.shields.io/jenkins/s/https/doi-janky.infosiftr.net/job/multiarch/job/i386/job/satosa.svg?label=i386)](https://doi-janky.infosiftr.net/job/multiarch/job/i386/job/satosa/) | [![mips64le build status badge](https://img.shields.io/jenkins/s/https/doi-janky.infosiftr.net/job/multiarch/job/mips64le/job/satosa.svg?label=mips64le)](https://doi-janky.infosiftr.net/job/multiarch/job/mips64le/job/satosa/) | [![ppc64le build status badge](https://img.shields.io/jenkins/s/https/doi-janky.infosiftr.net/job/multiarch/job/ppc64le/job/satosa.svg?label=ppc64le)](https://doi-janky.infosiftr.net/job/multiarch/job/ppc64le/job/satosa/) |
 | [![s390x build status badge](https://img.shields.io/jenkins/s/https/doi-janky.infosiftr.net/job/multiarch/job/s390x/job/satosa.svg?label=s390x)](https://doi-janky.infosiftr.net/job/multiarch/job/s390x/job/satosa/) | [![put-shared build status badge](https://img.shields.io/jenkins/s/https/doi-janky.infosiftr.net/job/put-shared/job/light/job/satosa.svg?label=put-shared)](https://doi-janky.infosiftr.net/job/put-shared/job/light/job/satosa/) |
 
-<!-- THIS FILE IS GENERATED BY https://github.com/docker-library/docs/blob/master/generate-repo-stub-readme.sh -->
+---
+
+## Git Commit Messages
+
+Please follow [Angular Commit Message Conventions](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-format). The following scopes are currently in use:
+- **docker-entrypoint**: the Dockerfile ENTRYPOINT scripts; currently only [docker-entrypoint.sh](docker-entrypoint.sh)
+- **docker-library**: the Docker Official Images library entry generator; currently only [generate-stackbrew-library.sh](generate-stackbrew-library.sh)
+- **dockerfile-linux**: all Linux variants of the container image itself; includes [Dockerfile-linux.template](Dockerfile-linux.template) and the corresponding variant image definitions in the SATOSA version-specific directories, e.g., [8.1/bullseye](8.1/bullseye)
+- **dockerfile-windows**: currently unused
+- **git**: Git repository configuration or GitHub-specific files; includes [.gitignore](.gitignore), [.gitattributes](.gitattributes), and [the GitHub Actions workflows](.github/workflows)
+- **license**: software licensing information; currently only [LICENSE.md](LICENSE.md)
+- **readme**: this file
+- **templating**: the gawk/jq-based templating engine itself, as opposed to the templates; currently only [apply-templates.sh](apply-templates.sh)
+- **update**: a helper script that executes both the version tracker and templating engine; currently only [update.sh](update.sh)
+- **versions**: the SATOSA version tracker; includes [versions.sh](versions.sh) and [versions.json](versions.json)
+
+## Update Process
+
+1. If necessary, update the list of version aliases at the beginning of `generate-stackbrew-library.sh`.
+
+2. Update `versions.json` and the container image definitions by running `update.sh`. Specify the desired major and minor version of SATOSA. For example:
+   ```bash
+   ./update.sh 8.1
+   ```
+
+3. If necessary, remove outdated versions of SATOSA or the base container images from `versions.json`. Delete the corresponding SATOSA container image definitions, e.g., `8.0/`, `8.1/*alpine3.14*/`.
+
+4. Commit all of the modified files. Mention the new SATOSA or base container version in the commit message subject. Reference the release announcement in the commit message body. For example:
+   ```
+   feat(*): version bump to SATOSA v8.1.0
+
+   Cf. https://github.com/IdentityPython/SATOSA/commit/d44b54433c5b817cf0409855881f6f2c80c27f5c
+   ```
+   Or for example:
+   ```
+   feat(*): version bump to Alpine Linux v3.16
+
+   Cf. https://www.alpinelinux.org/posts/Alpine-3.16.0-released.html
+   ```
+
+5. GitHub Actions will run two workflows on push. [Verify Templating](actions/workflows/verify-templating.yml) checks for uncommitted changes. [GitHub CI](actions/workflows/ci.yml) builds and tests all of the container images.
+
+6. If both workflows complete successfully, generate a new [Docker Official Images](https://github.com/docker-library/official-images/) library entry by running the following command:
+   ```bash
+   ./generate-stackbrew-library.sh
+   ```
+
+7. Fork and edit [the Docker Official Images library entry for SATOSA](https://github.com/docker-library/official-images/edit/master/library/satosa). Replace its contents with the output of `generate-stackbrew-library.sh`. Use a commit message referencing the release announcement. Submit a pull request when done. For example:
+   ```
+   Update SATOSA to v8.0.1
+
+   Cf. https://github.com/IdentityPython/SATOSA/commit/1a408439a6b8855346e5ca2c645dee6ab1ce8c0a
+   ```
+   Or for example:
+   ```
+   Update SATOSA base container images to Alpine Linux v3.16
+
+   Cf. https://www.alpinelinux.org/posts/Alpine-3.16.0-released.html
+   ```