[GitHub] [cordova-docs] raphinesse opened a new issue #1125: Remove docs for older versions from master branch

[GitBox <gi...@apache.org>]

raphinesse opened a new issue #1125:
URL: https://github.com/apache/cordova-docs/issues/1125


   # 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
   <!-- 
   Describe your feature request in detail
   Please provide any code examples or screenshots of what this feature would look like
   Are there any drawbacks? Will this break anything for existing users? 
   -->
   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/<LANG_IF_STILL_EXISTS>` 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/<VERSION_TAG>/www/docs/<LANG_IF_STILL_EXISTS>/<PAGE_PATH>`
   - 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.
   


----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@cordova.apache.org
For additional commands, e-mail: issues-help@cordova.apache.org