kubeflow
Improve version selector & rename "master" to "latest"
In the top right of the website, we have a "version selector" that lets you view archived versions of the docs from past releases, however, the current presentation is confusing to users.
New users expect that they should browse the site on the 1.9 branch for information about 1.9 (when in reality they should browse the master branch because we are always updating it).
In reality, we treat these historical snapshot versions as "snapshot archives" and don't go back to update them with content from master.
This PR makes the following changes to the version menu:
- Renamed the button which you click to expand the menu:
- For example, in this PR its
"Latest", but in thev1.0-branchsnapshot it would be"Archive: 1.0"
- For example, in this PR its
- prepended
Archive:to each version label - removes versions older than 0.6 from the dropdown
Screenshots
OLD
NEW
Thank you for creating those PRs @thesuperzapper.
From my point of view, we should not add
Archive:message to the previous Kubeflow versions since it can cause false impression that we don't provide support for those versions.
@andreyvelich the idea of the word "archive" is that it's an "archive" of the docs at that version, not that we don't support that version anymore.
Even if this was about support for the version itself, we definitely don't support anything other than 1.9.
Also, when you go to any of those old versions of the website, every page has something which explains this at the top (that you're viewing a snapshot, not the latest version), so it should be clear.
I would suggest that we follow Kubernetes way to show versions: https://kubernetes.io/. E.g. only leave 5 latests version of Kubeflow in the dropdown menu.
I don't really mind, but people might want to be able to see the older versions and they won't be able to find them otherwise.
I think we should probably keep at least all of the versions post 1.0.
What about the following?
- ~~master~~ -> 1.9
- ~~1.9~~
- 1.8
- 1.7
- 1.6
- 1.5
- 1.4
- 1.3
- 1.2
- 1.1
- 1.0
1.9 would be the latest docs version that comes from the master branch.
I like the idea of following what Kubernetes does and leaving all the post-1.0 versions.
What about the following?
- ~~master~~ -> 1.9
- ~~1.9~~
- 1.8
- 1.7
- 1.6
- 1.5
- 1.4
- 1.3
- 1.2
- 1.1
- 1.0
1.9 would be the latest docs version that comes from the
masterbranch.
@hbelmiro I agree, and this is what I have suggested for a number of releases. That is, we don't cut the 1.9 branch until we are close to releasing the 1.10 version.
The problem is it's very hard to know when to make that cut, because docs get added progressively, some from before the release is cut, and many after.
Also, in this particular case, we've already cut the 1.9 docs branch, so there is actually two different websites. Although, I would suggest most people should be reading the latest/master version if they are using 1.9, or even 1.8.
However, there is value to storing an "archive" of the docs at the time of each release (even if new docs are subsequently added to master).
So that leaves us with what I am suggesting we do in this PR, which is just making it more clear that those old versions are actually archives, and not going to be updated, and pointing people towards master.
@andreyvelich the idea of the word "archive" is that it's an "archive" of the docs at that version, not that we don't support that version anymore.
@thesuperzapper What is the user value to add archive message to the versions that we display on the website ?
Even if this was about support for the version itself, we definitely don't support anything other than 1.9.
Why we don't support anything older than 1.9 ? I think, that similar to Kubernetes we should provide support to the few most recent Kubeflow releases and provide critical bug fixes for that release. That will show the project stability and maturity for the end users.
I don't really mind, but people might want to be able to see the older versions and they won't be able to find them otherwise.
We can have dedicated page for old Kubeflow versions, like in Kubernetes: https://kubernetes.io/docs/home/supported-doc-versions/#versions-older
@andreyvelich the idea of the word "archive" is that it's an "archive" of the docs at that version, not that we don't support that version anymore.
@thesuperzapper What is the user value to add
archivemessage to the versions that we display on the website ?
Very simply:
- Those
v1.X-branch...website are archives, in the sense that they are the state of the docs at the time of the release. - Users are best served by reading the
master/latestversion of the website. - It helps users understand quickly that this is not a "versioned docs site" like they are probably expecting.
Do you have an alternative word that we could use as a prefix?
If you can't stand the "archive" prefix (and we can't think of an alternative), I guess as long as all the archive sites highlight at the top that you are not looking at the latest version (which will be the case after the other PRs are merged), we could drop it.
Even if this was about support for the version itself, we definitely don't support anything other than 1.9.
Why we don't support anything older than 1.9 ? I think, that similar to Kubernetes we should provide support to the few most recent Kubeflow releases and provide critical bug fixes for that release. That will show the project stability and maturity for the end users.
While that is nice in theory, it's a separate discussion to this as we currently don't support anything but 1.9.0.
This PR is not about the actual support status of each version, but helping users understand that they are looking at a docs "snapshot/archive".
Users are best served by reading the master/latest version of the website.
What if some new features that we deliver are not compatible with the old version of the components ? In that case, users who are using old version of this Kubeflow component have to read previous version of Kubeflow website.
While that is nice in theory, it's a separate discussion to this as we currently don't support anything but 1.9.0.
This is not 100% true, at least from the @kubeflow/wg-training-leads side we can fix the critical bugs on the previous versions (e.g. three latest releases) of Training Operator if that was asked by users.
@thesuperzapper Why the Kubernetes approach doesn't work for us ?
I want to get @StefanoFioravanzo feedback on this given that he spent time to think about how we can develop the Kubeflow website given that every Kubeflow sub-project has dedicated release cycle and version.
@andreyvelich really, we just need to make a decision on if the "Achive: " prefix will be present or not.
The other PRs are much more important and I don't want to let this discussion block them, we need to prevent Google from indexing the very old websites (right now, Kubeflow search results often surface results from 0.3/0.6 versions of the docs):
- https://github.com/kubeflow/website/pull/3848
- Already merged, because it does not add the "archive: " prefix.
- https://github.com/kubeflow/website/pull/3847
- Already merged, because it does not add the "archive: " prefix.
- https://github.com/kubeflow/website/pull/3849
- https://github.com/kubeflow/website/pull/3850
- https://github.com/kubeflow/website/pull/3851
- https://github.com/kubeflow/website/pull/3852
- https://github.com/kubeflow/website/pull/3853
- https://github.com/kubeflow/website/pull/3854
- https://github.com/kubeflow/website/pull/3855
- https://github.com/kubeflow/website/pull/3856
- https://github.com/kubeflow/website/pull/3857
- https://github.com/kubeflow/website/pull/3858
- https://github.com/kubeflow/website/pull/3859
- https://github.com/kubeflow/website/pull/3860
- https://github.com/kubeflow/website/pull/3861
- https://github.com/kubeflow/website/pull/3862
Once we agree on if the "Archive: " prefix will be present, I will update these PRs to reflect that (so all versions are consistent), but its way more important to stop them appearing in search results.
Hmm https://github.com/kubeflow/website/pull/3849 seems merged already
Hmm #3849 seems merged already
@terrytangyuan Either way, its easy to update now that I have fixed building.
The other PRs are much more important and I don't want to let this discussion block them, we need to prevent Google from indexing the very old websites (right now, Kubeflow search results often surface results from 0.3/0.6 versions of the docs):
@thesuperzapper Can you remove the version change from your PRs and only leave the change to prevent Google from indexing and we can merge those PRs ?
@andreyvelich I have updated all the other PRs with the following changes:
- Remove the "Archive: " prefix from the "versions" menu that I added before
- Update the root OWNERS to align with the current
master(KSC members) - Updated the "version banner" to look like this:
We now need someone with GitHub org admin manually merge the following PRs:
- A manual merge is needed because the old OWNERs are not active anymore.
- WARNING: please remember to use SQUASH merge!
- https://github.com/kubeflow/website/pull/3869
- https://github.com/kubeflow/website/pull/3868
- https://github.com/kubeflow/website/pull/3867
- https://github.com/kubeflow/website/pull/3850
- https://github.com/kubeflow/website/pull/3851
- https://github.com/kubeflow/website/pull/3852
- https://github.com/kubeflow/website/pull/3853
- https://github.com/kubeflow/website/pull/3854
- https://github.com/kubeflow/website/pull/3855
- https://github.com/kubeflow/website/pull/3856
- https://github.com/kubeflow/website/pull/3857
- https://github.com/kubeflow/website/pull/3858
- https://github.com/kubeflow/website/pull/3859
- https://github.com/kubeflow/website/pull/3860
- https://github.com/kubeflow/website/pull/3861
- https://github.com/kubeflow/website/pull/3862
@james-jwu or @zijianjoy can you please update these DNS records, as they don't point to our modern Netlify, so will not be updated otherwise:
-
v0-2.kubeflow.org:- OLD
CNAME:eager-nobel-1708cf.netlify.com - NEW
CNAME:v0-2-branch--competent-brattain-de2d6d.netlify.app
- OLD
-
v0-3.kubeflow.org:- OLD
CNAME:competent-jones-a15cc2.netlify.com - NEW
CNAME:v0-3-branch--competent-brattain-de2d6d.netlify.app
- OLD
-
v0-4.kubeflow.org:- OLD
CNAME:infallible-hermann-cb44b2.netlify.com - NEW
CNAME:v0-4-branch--competent-brattain-de2d6d.netlify.app
- OLD
-
v0-5.kubeflow.org:- OLD
CNAME:practical-neumann-e70801.netlify.com - NEW
CNAME:v0-5-branch--competent-brattain-de2d6d.netlify.app
- OLD
-
v0-6.kubeflow.org:- OLD
CNAME:v0-6-branch--competent-brattain-de2d6d.netlify.com - NEW
CNAME:v0-6-branch--competent-brattain-de2d6d.netlify.app
- OLD
-
v0-7.kubeflow.org:- OLD
CNAME:v0-7-branch--competent-brattain-de2d6d.netlify.com - NEW
CNAME:v0-7-branch--competent-brattain-de2d6d.netlify.app
- OLD
@kubeflow/kubeflow-steering-committee @kubeflow/wg-pipeline-leads @kubeflow/wg-data-leads @kubeflow/wg-training-leads @kubeflow/wg-notebooks-leads @kubeflow/wg-manifests-leads Can you give +1 on the banner that @thesuperzapper proposed for the old docs ?
If that looks good to you, we can start merging the PRs on the old website branches.
@thesuperzapper Only one comment from me, that I don't think that we should add yellow banner on the 1.9 documentation, since it is the latest stable release. As you can see, the Kubernetes doesn't have this banner on the latest v1.31 version:
- https://kubernetes.io/docs/concepts/workloads/controllers/job/
- https://v1-30.docs.kubernetes.io/docs/concepts/workloads/controllers/job/
WDYT @thesuperzapper ?
@thesuperzapper Only one comment from me, that I don't think that we should add yellow banner on the 1.9 documentation, since it is the latest stable release. As you can see, the Kubernetes doesn't have this banner on the latest v1.31 version:
- https://kubernetes.io/docs/concepts/workloads/controllers/job/
- https://v1-30.docs.kubernetes.io/docs/concepts/workloads/controllers/job/
WDYT @thesuperzapper ?
@andreyvelich on the Kubernetes docs, "1.31" is actually a link to kubernetes.io, which is their master branch.
The problem is that we have already cut a v1.9-branch for "1.9", so it really is a "snapshot of the docs at the time of the 1.9 release". If we don't have the warning, people won't realize they are not viewing the updated version of the 1.9 docs (which live on master).
In the future, I think we should hold off on cutting the 1.10 branch until just before we start merging docs for the 1.11 release. To resolve the current situation, we have two options:
- OPTION 1: Keep the current
v1.9-branchand retain the warning header. - OPTION 2: Delete the current
v1.9-branchand only re-create it once we start the 1.10 release process
"While that is nice in theory, it's a separate discussion to this as we currently don't support anything but 1.9.0." yes there is just not much capacity beyond that. This might change if someone volunteers. We only fix critical things that are easy to fix, so in practice it was around 1 Year for 1.8/1.8.1 and with 1.9.1 released 1.8.1 will be EOL for most developers. For longer support you probably need distributions, consultants etc.
I like the term master more than latest, but I am also in favour of pushing for the master/latest version being shown by default and marking everything 2 releases away, so 1.8.1 and older as archived, snapshot, xxx End of Life or so.
/lgtm
I can see the dropdown and the version banner in the linked PRs, thank you!
As we discussed during today's community call, we can manually squash + merge all PRs to disable indexing on old branches. We should just have followup discussion for the PR on 1.9 branch. @johnugeorge @terrytangyuan @james-jwu @jbottum Can you help to manually squash + merge these PRs if you are agree with the banner: https://github.com/kubeflow/website/pull/3869 https://github.com/kubeflow/website/pull/3868 #3867 https://github.com/kubeflow/website/pull/3850 https://github.com/kubeflow/website/pull/3851 https://github.com/kubeflow/website/pull/3852 https://github.com/kubeflow/website/pull/3853 https://github.com/kubeflow/website/pull/3854 https://github.com/kubeflow/website/pull/3855 https://github.com/kubeflow/website/pull/3856 https://github.com/kubeflow/website/pull/3857 https://github.com/kubeflow/website/pull/3858 https://github.com/kubeflow/website/pull/3859 https://github.com/kubeflow/website/pull/3860 https://github.com/kubeflow/website/pull/3861
Both the DNS configuration and the Kubeflow website hosting on Netlify are transferred to CNCF. Would you like to make a request to CNCF by submitting a service deck ticket? https://cncfservicedesk.atlassian.net/servicedesk/customer/portals
it seems like there are several activities in this PR. I am a -1 on the initial proposal to change from master, 1.9. i.e. I am -1 on latest and archive proposal.
This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
This pull request has been automatically closed because it has not had recent activity.You can reopen the PR if you want.
We still need to decide what to do here regarding "master", but the "archived message" update from this PR is still important for when we branch off future release branches (and set the archived flag to true).
/reopen
@thesuperzapper: Reopened this PR.
In response to this:
We still need to decide what to do here regarding "master", but the "archived message" update from this PR is still important for when we branch off future release branches (and set the archived flag to true).
/reopen
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.
![google-oss-prow[bot] avatar](https://avatars.githubusercontent.com/in/143327?v=4 "Published by a pub.dev verified publisher"){kind=small}
[APPROVALNOTIFIER] This PR is NOT APPROVED
This pull-request has been approved by: Once this PR has been reviewed and has the lgtm label, please assign franciscojavierarceo for approval. For more information see the Kubernetes Code Review Process.
The full list of commands accepted by this bot can be found here.
Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment