-
Notifications
You must be signed in to change notification settings - Fork 14.2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Revise approach for documenting multiple Kubernetes versions #23518
Comments
Yes, this brings up some good questions and ideas. |
Issues go stale after 90d of inactivity. If this issue is safe to close now please do so with Send feedback to sig-testing, kubernetes/test-infra and/or fejta. |
Stale issues rot after 30d of inactivity. If this issue is safe to close now please do so with Send feedback to sig-testing, kubernetes/test-infra and/or fejta. |
FWIW, etcd-io/website#82 is a somewhat-related discussion about multiple versions for etcd documentation. |
/remove-lifecycle rotten |
I expect that moving to a |
In slack, @sftim, you mentioned wanting to surface all of the previous k8s documentation versions. I like this idea. If we do surface all the old versions, we may want to reconsider how we're presenting those older versions. The "current +4 versions" drop-down box works well now because it is a short list, but if we include all previous versions that drop-down would quickly become unwieldy. Potentially we could set up a previous versions page that would provide some more context for each version. |
Thinking about these two things together: this could greatly increase the size of the site. I've been looking at this style of versioning for etcd - and I think that it works well for small to medium sized sites, at least the way I've seen it set up using folders (there may be other ways of achieving this organization). The Kubernetes site is much bigger than the sites I've seen managing versioning with a folder system though. If we were to place all ~20 previous versions each in their own folder under With all languages in, I think the Docs section of the Kubernetes website is ~6500 files and ~65 MB (current version, older versions would likely be smaller). If we include all ~20 versions in one repo, we'll inflate that to ~1.3 GB. I've seen the deploy log for v1.16, and it takes about 7 minutes to do the full deploy. Building the sites currently takes about 0.3 minutes of that (~23000 ms). If we have to build all 20 versions each time we deploy (or deploy preview), we may be adding about 6 minutes to the overall deploy (Rounding down because older versions may be smaller, and I'm not very familiar with Hugo & Netlify yet, they may do some clever things to speed this up). This would be fairly easy to test though - we could just copy the current |
So, having written about how maybe not to do this, I've been thinking about how maybe we could do this :) I haven't thought of a really clever way of doing it yet, and I keep coming back to @sftim's initial comment:
This would likely be a lot of work up front, but is probably the simplest way to go -- the updates would be fairly straightforward, but there would be a lot of them. Setting up a matrix of issues (or a spreadsheet) to organize these updates would be helpful. We maybe able to cherry pick commits between versions to reduce this workload (i was able to employ this on the CNI version branches, but that was a much smaller site, and I was the only one working on the versioning system at the time). The
Proxy model - this is sort of how we're already doing it, but we're using Netlify's whole service as the proxy. I've seen API services where each path gets sent to a different service provider/server (using tools like nginx). We could potentially build and publish only the |
Issues go stale after 90d of inactivity. If this issue is safe to close now please do so with Send feedback to sig-contributor-experience at kubernetes/community. |
Stale issues rot after 30d of inactivity. If this issue is safe to close now please do so with Send feedback to sig-contributor-experience at kubernetes/community. |
/remove-lifecycle rotten |
PR #29504 may solve a lot of my concerns about build time if we go with a folder based versioning system and build each version every time we do a release or deploy preview. |
The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs. This bot triages issues and PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. This bot triages issues and PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle rotten |
/remove-lifecycle rotten |
The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs. This bot triages issues and PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
Hugo has made an update and introduced a new feature that may help us to manage versions better: I haven’t played with it much yet, but if I’m reading this correctly, it looks like we may be able to have a base version, then for any new version, only create deltas (and, I think we may be able to do this for both release version and language). This may give us a path away from versioning the whole site the way we currently do with subdomains. /cc @chalin |
/remove-lifecycle stale |
/triage accepted |
#23518 (comment) sounds great! |
The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs. This bot triages issues and PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs. This bot triages issues and PRs according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle rotten |
/remove-lifecycle rotten |
Issue #37871 is broadly similar |
Anyone who'd like to help with this issue is very welcome to work on it. |
@chrisnegus would you like to contribute towards this? |
I wonder whether we can freeze the HTML for the archived minor release docs, maybe doing a full rebuild once a week. I suspect we do have the technology for that. |
I'm starting work on this. I'll report back here when I have made some progress. |
This is a Feature Request
What would you like to be added
Kubernetes offers online documentation for the current release and the four previous minor releases.
In this issue I'm proposing that, aside from pages inside
/docs/
(and its localized equivalents), we should always serve current content.Possible approaches:
/blog/
,/training/
etc to the live site/docs/v1.18/home/
and/docs/v1.19/home/
etcWhy is this needed
At the time of writing for example you can visit https://v1-18.docs.kubernetes.io/blog/ and see an archived view of the blog.
I don't think that's particularly helpful to anyone.
Worse, links to old docs versions stop working relatively soon, and that's unhelpful. People get a TLS error instead of old docs - see Revise approach for documenting multiple Kubernetes versions #23518 (comment).
Comments
Let's discuss whether we want this and, if so, how we want it to work. It's going to be at least a medium-sized chunk of work to implement, I suspect.
/kind feature
/area web-development
The text was updated successfully, but these errors were encountered: