Skip to main content

ADR-0005: Provide Versioned Documentation

Status:REJECTED
Date:2020-10-12
Author(s):Yannik Fuhrmeister yannik.fuhrmeister@iteratec.com, Sven Strittmatter sven.strittmatter@iteratec.com
info

Since nearly two years no one cared about versioned documentation, so we reject this proposal.

Context​

We want to introduce versioning to be able to provide documentation 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 repository (see https://v2.docusaurus.io/docs/versioning/#directory-structure)