Skip to main content

adr_0006

ADR-0006: How We Want to Handle Versions in Our Documentation

Status:PROPOSED
Date:2020-10-12
Author(s):Yannik Fuhrmeister yannik.fuhrmeister@iteratec.com

Context#

We want to introduce versioning to be able to provide dokumentation for multiple versions of the SecureCodeBox. The tool that we are currently using for documentation is Docusaurus. Docusaurus provides the possibility to maintain multiple versions out of the box (https://v2.docusaurus.io/docs/versioning/).

We will need to specify how many versions of the documentation we want to maintain to avoid inconsistencies and overhead. Furthermore, we need to decide which version increments need to have their own branch of documentation.

Decision#

  • We introduce a new documentation version for every minor version (https://semver.org/) to ensure that the documentation is up to date
  • We maintain the latest 3 major versions (previous, current, next)
  • We maintain the latest minor version for each major version
  • We do not maintain patch versions nor multiple minor versions for each major version!
  • Example: For SecureCodeBox versions 1.9.9, 2.3.2, 2.3.3 and 3.0.0 the documentation versions would be 1.9.x, 2.3.x and 3.0.x
  • TL;DR We maintain 3 versions of the documentation

Consequences#

  • We need to update the documentation version everytime we increment minor or major versions of the SecureCodeBox (manually or with action)
  • Maintaining the documentation could be more difficult due to now increased number of documentation files
  • Documentation has to be maintained in two repositories because when creating a new version Docusaurus creates a copy of all files in this respository (see https://v2.docusaurus.io/docs/versioning/#directory-structure)