apache / apache/cordova-docs

Remove docs for older versions from master branch

Open
#1,125 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
353
Forks
565
Avg merge
7h 15m
Merged PRs (30d)
5

Description

# Feature Request

## Motivation Behind Feature
We build the docs for all versions of Cordova ever included in this repository every time we build the website/docs. This has several disadvantages:

- it is detrimental to build performance
- it complicates the build process, making it harder to maintain or evolve

That being said, I think it is a good thing that the docs for old versions are easily accessible and I think they should continue to be.

_Note:_ This is supposed to be tackled after #995.

## Feature Description

A possible solution to this problem might be found in the way Electron handles its docs. The latest version of their docs is templated, styled and integrated into the website. On each docs page you have a version selection (we already have something like that too). But instead of linking to another built version of the docs, this selector links to the corresponding Markdown file in the GitHub repo. Thus you can easily find an old version of a docs page but need not build these docs every time you build the site.

So I suggest we do the following:
- keep only the docs for the latest version in `www/docs/` i.e. delete everything except `dev/` from that directory and replace `dev/` with its contents.
- when releasing a version, create a tag and/or branch that points to the appropriate commit that has the docs for that version
- during build, create a version selector based on these tags.
We can even do this per-page, excluding versions that do not have the corresponding page (this should require very build-time little overhead if we only collect the required information from git once). For a given page and version, this selector would link to `https://github.com/apache/cordova-docs/tree//www/docs//`
- Create corresponding commits & tags/branches for existing versions
- Create redirects for the old version URLs. Simple regex matching should be enough here

If we need to do more than templating, i.e. generate markdown from certain sources, then we should commit these build artifacts to the repo (in the respective version tag/branch) and link to the built Markdown of course.

Implementing the described approach would only ever build one version of the docs, while still providing an archive of previous version via our GitHub repository and GitHub's plain markdown rendering.

## Alternatives

Instead of linking to the repo for older versions, keep an archive of built web-pages on the web server and link to these instead. This has the disadvantage that the archived files could be accidentally deleted and then would need to be rebuilt.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the work required by #995, then inspect www/docs/ and the current documentation build and version-selection process. Done means only the latest docs are built from master, existing versions remain accessible through tags or branches, old URLs redirect, and the selector links to the appropriate archived version.

Written by the indexing model from the issue text.

Assessment

Tech stack
github
Domain
build-system, documentation, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.