debezium / debezium/dbz

Legacy documentation builder

Open
#2,389 0 comments 0 reactions 1 assignee Claimed by @Naros View on GitHub
component/website type/task
Dominant language
HTML
Stars
6
Forks
8
Avg merge
2d 19h
Merged PRs (30d)
1

Description

Up until now, when a specific release stream is deprecated, e.g., 1.x or 2.x, we would mark all but the last "major.minor" version as being hidden, removing it from the website's version/documentation overview pages and pickers, and we'd remove it from the `playbook.yml` used by the website builder process. This is done to keep the website build process lean and fast.

However, users are often using older versions, and despite those versions no longer being supported or maintained by the community, documentation availability is still a concern.

## Proposal

Create a specialized `rake` command that uses a separate playbook file, similar to how `author` uses the `playbook_author.yml`. Initially, this special playbook file can be managed manually as a copy of `playbook.yml` and include the versions that are considered legacy. When using this task, the documentation pages should ideally be rendered to the `documentation` directory and committed as a one-off.

The normal `rake` build step should automatically (without any change hopefully) take this static content and copy it byte-for-byte into the target `_site` directory on builds, so that the net result is that the `documentation/reference` directory structure contains the legacy docs from the git history plus the dynamically maintained docs from the automated build step.

The next bit would be to replace the hidden/displayed (not sure which it is) marker in the YAML files for versions with a new one marked legacy. A legacy marker will show a special colored "legacy" banner on the version/documentation box so users know it's no longer maintained compared to the development, latest stable, and stable banners.

The final part is the version picker in the documentation. For this, there are a variety of ways we could make this work, but given that we already have custom partials for the supplemental UI, our `rake` build step creates a special file in the `_site/documentation` folder called `docs-manifest.json` or similar that outlines which versions are stable vs prerelease, sourced from all our YAML files as a distinct set of versions listed in YAML. The version picker partial will fetch the version manifest dynamically at runtime and populate the picker versions automatically.

## TL;DR

* No change in the YAML data files that are currently maintained. What we currently do is unchanged.
* New `rake` command we run after marking old data versions as legacy to create static doc builds for those versions.
* New Antora legacy playbook used to build legacy docs.
* Legacy documentation files are stored statically as part of the main website repository.
* Existing website URLs and ways of accessing documentation remain unchanged (aside from making old versions visible again)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.