Added a versioning policy to the documentation.

Closes #8748.

docker/docker-compose.yml

@@ -1,4 +1,4 @@
-# Base docker composition. For development, this composition is augmented in docker-compose.override.yml.
+# Base Docker-composition. For development, this composition is augmented in docker-compose.override.yml.
 
 services:
   www:

docs/src/changelog.md

@@ -12,7 +12,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Deployment notes
 
-If your currently installed *Quality-time* version is v4.10.0 or older, please read the v5.0.0 deployment notes first.
+If your currently installed *Quality-time* version is not v5.13.0, please first check the upgrade path in the [versioning policy](versioning.md).
 
 ### Fixed
 
@@ -23,6 +23,7 @@ If your currently installed *Quality-time* version is v4.10.0 or older, please r
 
 - Group digits in numbers. Closes [#8076](https://github.com/ICTU/quality-time/issues/8076).
 - In the measurement entity status menu, the description of the menu items would say "undefined days" if the desired response time for the status had not been changed from its default value. Fixes [#8284](https://github.com/ICTU/quality-time/issues/8284).
+- Added a [versioning policy](versioning.md) to the documentation. Closes [#8748](https://github.com/ICTU/quality-time/issues/8748).
 - Allow for specifying supported source versions in the data model. Show the supported source version in the UI and the reference documentation. Closes [#8786](https://github.com/ICTU/quality-time/issues/8786).
 
 ### Changed
@@ -338,7 +339,7 @@ If your currently installed *Quality-time* version is v4.10.0 or older, please r
 
 If your currently installed *Quality-time* version is v4.0.0 or older, please read the v4.0.0 deployment notes first.
 
-In this version of *Quality-time* the internal server component is no longer used. The notifier and collector components talk directly to the database, instead of using the internal server. This means that the docker composition **must** be changed:
+In this version of *Quality-time* the internal server component is no longer used. The notifier and collector components talk directly to the database, instead of using the internal server. This means that the Docker-composition **must** be changed:
 
 - Remove the `internal_server` section.
 - Rename the `external_server` section to `api_server` and make the following changes in that section:
@@ -646,7 +647,7 @@ If your currently installed *Quality-time* version is v4.0.0 or older, please re
 
 If your currently installed *Quality-time* version is not v3.37.0, please read the v3.37.0 deployment notes first.
 
-This version of *Quality-time* splits the server component into two: an external server component serving the external API and an internal server component serving the collector and notifier components. This means that the docker composition **must** be changed:
+This version of *Quality-time* splits the server component into two: an external server component serving the external API and an internal server component serving the collector and notifier components. This means that the Docker-composition **must** be changed:
 
 - Rename the `server` service to `external_server`.
   - Use the image `ictu/quality-time_external_server`.
@@ -1153,7 +1154,7 @@ Background information: *Quality-time* uses MongoDB as database component. A Mon
 
 ### Changed
 
-- Wrap the database (MongoDB), proxy (Caddy) and renderer (url-to-pdf-api) in *Quality-time* images, so these components have the same version number as the other components and don't need to be updated by downstream maintainers separately. Note that your Docker composition needs to be changed once to use these new *Quality-time* images. See the example [docker-compose.yml](https://github.com/ICTU/quality-time/blob/master/docker/docker-compose.yml). Closes [#1770](https://github.com/ICTU/quality-time/issues/1770).
+- Wrap the database (MongoDB), proxy (Caddy) and renderer (url-to-pdf-api) in *Quality-time* images, so these components have the same version number as the other components and don't need to be updated by downstream maintainers separately. Note that your Docker-composition needs to be changed once to use these new *Quality-time* images. See the example [docker-compose.yml](https://github.com/ICTU/quality-time/blob/master/docker/docker-compose.yml). Closes [#1770](https://github.com/ICTU/quality-time/issues/1770).
 - Increase render timeout so that larger reports can be exported to PDF. Closes [#1771](https://github.com/ICTU/quality-time/issues/1771).
 - Add no-cache option for /api/v3/logo to the Caddy configuration.
 
@@ -1273,7 +1274,7 @@ Background information: *Quality-time* uses MongoDB as database component. A Mon
 ### Added
 
 - Support for Forwarded Authentication in a situation where *Quality-time* is behind a reverse proxy that is responsible for authentication. See the [deployment instructions](deployment.md#forwarded-authentication).
-- Notifications of new red metrics to Microsoft Teams, using webhooks. See the [user manual](usage.md#notifications). Note that your Docker composition needs to be changed to include the new notifier component. See the example [docker-compose.yml](https://github.com/ICTU/quality-time/blob/master/docker/docker-compose.yml) and the [deployment instructions](deployment.md). Partially implements [#1223](https://github.com/ICTU/quality-time/issues/1223).
+- Notifications of new red metrics to Microsoft Teams, using webhooks. See the [user manual](usage.md#notifications). Note that your Docker-composition needs to be changed to include the new notifier component. See the example [docker-compose.yml](https://github.com/ICTU/quality-time/blob/master/docker/docker-compose.yml) and the [deployment instructions](deployment.md). Partially implements [#1223](https://github.com/ICTU/quality-time/issues/1223).
 
 ## v3.9.0 - 2020-10-11
 
@@ -1482,7 +1483,7 @@ Background information: *Quality-time* uses MongoDB as database component. A Mon
 
 ### Changed
 
-- Moved the Copy and Move buttons next to the Add buttons, making the UI more consistent. This also allows the user to copy an existing item to the right position in one go, instead of having to copy and then move it. To support adding items by copying an existing item, the API has been updated to version 3. Version 2 of the API is deprecated. See <http://quality-time.example.org/api/>, <http://quality-time.example.org/api/v2>, and <http://quality-time.example.org/api/v3>. Note that your Docker composition may need to be changed to use the new API version. See the Caddy proxy configuration in the example [docker-compose.yml](https://github.com/ICTU/quality-time/blob/master/docker/docker-compose.yml). Closes [#1197](https://github.com/ICTU/quality-time/issues/1197).
+- Moved the Copy and Move buttons next to the Add buttons, making the UI more consistent. This also allows the user to copy an existing item to the right position in one go, instead of having to copy and then move it. To support adding items by copying an existing item, the API has been updated to version 3. Version 2 of the API is deprecated. See <http://quality-time.example.org/api/>, <http://quality-time.example.org/api/v2>, and <http://quality-time.example.org/api/v3>. Note that your Docker-composition may need to be changed to use the new API version. See the Caddy proxy configuration in the example [docker-compose.yml](https://github.com/ICTU/quality-time/blob/master/docker/docker-compose.yml). Closes [#1197](https://github.com/ICTU/quality-time/issues/1197).
 
 ### Fixed
 

docs/src/deployment.md

@@ -2,14 +2,22 @@
 
 This document describes how to deploy, and if needed move, the *Quality-time* application. It is aimed at *Quality-time* operators.
 
-*Quality-time* consists of a set of Docker containers that together form the application. See the [software documentation](software.md) for an overview of the different containers. It is assumed the containers are deployed using a docker-composition. An alternative deployment based on a Helm chart and intended for an OpenShift (Kubernetes) cluster is described in the [Helm for OpenShift README](https://github.com/ICTU/quality-time/tree/master/openshift/helm/README.md).
+*Quality-time* consists of a set of Docker containers that together form the application. See the [software documentation](software.md) for an overview of the different containers. It is assumed the containers are deployed using a Docker-composition. An alternative deployment based on a Helm chart and intended for an OpenShift (Kubernetes) cluster is described in the [Helm for OpenShift README](https://github.com/ICTU/quality-time/tree/master/openshift/helm/README.md).
 
 *Quality-time* furthermore assumes an LDAP service is available to authenticate users or that forwarded authentication is used.
 
+```{warning}
+Before skipping versions or downgrading, see the [version policy](versioning.md).
+```
+
 ## Docker-composition
 
 This document assumes docker-compose is used to deploy the containers. The [docker folder](https://github.com/ICTU/quality-time/tree/master/docker) of the *Quality-time* repository contains different compose files for running *Quality-time* in development and continuous integration mode. You can use these compose files as basis for your own deployment configuration.
 
+```{note}
+Per the [version policy](versioning.md), if the Docker-composition needs changes, this will be indicated by a new major release of *Quality-time*.
+```
+
 To deploy *Quality-time* locally, follow these steps:
 
 1. Make a directory, e.g. `quality_time` and change directory to it.
@@ -126,7 +134,7 @@ By default, the notifier wakes up every minute to check for changed metric statu
 
 ## Configuring MongoDB credentials (optional)
 
-The default MongoDB credentials can be changed as follows:
+The default {index}`MongoDB` credentials can be changed as follows:
 
 ```yaml
   database:
@@ -139,7 +147,7 @@ See the [documentation on the MongoDB image](https://hub.docker.com/_/mongo) for
 
 ## Configuring renderer localisation (optional)
 
-The date/time format and timezone of the reports that user sees are determined by the user's browser. To configure the date/time format and timezone of exported PDFs, the renderer can be configured as follows:
+The date/time format and timezone of the reports that a user sees are determined by the user's browser. To configure the date/time format and timezone of exported PDFs, the renderer can be configured as follows:
 
 ```yaml
   renderer:

docs/src/development.md

@@ -471,14 +471,16 @@ python release.py --help
 
 ### Decide the release type
 
-*Quality-time* adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html), so first you need to decide on the type of release you want to create:
+*Quality-time* adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html), so first you need to decide on the type of release you want to create, conform the [release policy](versioning.md#major-minor-and-patch-releases).
 
-- Create a **major** release if the next release contains backwards incompatible changes, and optionally other changes and bug fixes.
-- Create a **minor** release if the next release contains non-breaking changes, and optionally bug fixes.
-- Create a **patch** release if the next release contains bug fixes only.
+- Create a **major** release if an operator needs to make manual changes to the Docker-composition before deploying the next release.
+- Create a **minor** release if the next release contains new or changed functionality.
+- Create a **patch** release if the next release contains only bug fixes.
 
 If you want to test the release (for example, deploy it to a test environment, or roll out a release to early adopters), it's possible to create a **release candidate** for a major, minor, or patch release.
 
+If the release type is major, minor, or patch, update the [version overview](versioning.md#version-overview).
+
 ```{important}
 To determine whether a release is major, minor, or patch, compare the changes to the [previous most recent release](changelog.md), excluding release candidates.
 ```
@@ -534,7 +536,7 @@ Base images used in the Docker containers, and additionally installed software,
 - [Collector](https://github.com/ICTU/quality-time/blob/master/components/collector/Dockerfile): the Python base image.
 - [Notifier](https://github.com/ICTU/quality-time/blob/master/components/notifier/Dockerfile): the Python base image.
 - [Frontend](https://github.com/ICTU/quality-time/blob/master/components/frontend/Dockerfile): the Node base image, the curl version, the npm version, and the serve version.
-- [Database](https://github.com/ICTU/quality-time/blob/master/components/database/Dockerfile): the MongoDB base image.
+- [Database](https://github.com/ICTU/quality-time/blob/master/components/database/Dockerfile): the {index}`MongoDB` base image.
 - [Proxy](https://github.com/ICTU/quality-time/blob/master/components/proxy/Dockerfile): the Nginx base image.
 - [Renderer](https://github.com/ICTU/quality-time/blob/master/components/renderer/Dockerfile): the Node base image, the curl version, the Chromium version, and the npm version.
 - [Test data](https://github.com/ICTU/quality-time/blob/master/components/testdata/Dockerfile): the Python base image.

docs/src/index.md

@@ -37,6 +37,7 @@ reference.md
 ```{toctree}
 :maxdepth: 1
 :caption: Technical documentation 🛠
+versioning.md
 deployment.md
 development.md
 software.md

docs/src/software.md

@@ -378,14 +378,12 @@ The proxy uses the following environment variables:
 
 ## Database
 
-The database component consists of a [Mongo](https://www.mongodb.com) database to store reports and measurements.
+The database component consists of a [MongoDB](https://www.mongodb.com) database to store reports and measurements.
 
-The proxy [Dockerfile](https://github.com/ICTU/quality-time/blob/master/components/database/Dockerfile) wraps the MongoDB image in a *Quality-time* image so the MongoDB version number can be changed when needed.
+The proxy [Dockerfile](https://github.com/ICTU/quality-time/blob/master/components/database/Dockerfile) wraps the {index}`MongoDB` image in a *Quality-time* image so the MongoDB version number can be changed when needed.
 
 *Quality-time* stores its data in a Mongo database using the following collections: `datamodels`, `measurements`, `reports`, `reports_overviews`, and `sessions`.
 
-The two server components are the only components that directly interacts with the database.
-
 Data models, reports, and reports overviews are [temporal objects](https://www.martinfowler.com/eaaDev/TemporalObject.html). Every time a new version of the data model is loaded or the user edits a report or the reports overview, an updated copy of the object (a "document" in Mongo-parlance) is added to the collection. Since each copy has a timestamp, this enables the API-server to retrieve the documents as they were at a specific moment in time and provide time-travel functionality.
 
 ### Environment variables
@@ -425,7 +423,7 @@ This component contains test data for the example reports. The Docker image is p
 
 ### Running the test data component
 
-The test data component is started as part of the [docker composition](https://github.com/ICTU/quality-time/blob/master/docker/docker-compose.override.yml) for development, see the [developer manual](development.md).
+The test data component is started as part of the [Docker-composition](https://github.com/ICTU/quality-time/blob/master/docker/docker-compose.override.yml) for development, see the [developer manual](development.md).
 
 To serve the test data locally, you can also start a web server from a console, for example: