Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Support always-latest links to versioned docs #221

Open
huonw opened this issue Jun 9, 2024 · 5 comments
Open

Support always-latest links to versioned docs #221

huonw opened this issue Jun 9, 2024 · 5 comments
Labels
enhancement New feature or request

Comments

@huonw
Copy link
Contributor

huonw commented Jun 9, 2024 •
edited
Loading

Currently the docs for each version of Pants have a version in the URL, e.g. https://www.pantsbuild.org/2.21/docs/introduction/welcome-to-pants

In https://chat.pantsbuild.org/t/18888509/does-the-new-docsite-allow-latest-links-we-don-t-want-to-alw#17a3e060-95da-4879-a1e9-7254e042288b / https://pantsbuild.slack.com/archives/C0D7TNJHL/p1717762737437129 , there's discussion that this can be annoying in some circumstances, and it might be nice to support URLs that always point to the latest stable release, for instance, we're up to 2.21.0, so maybe one of these could be currently equivalent to the link above... and when we release 2.22 they'd automatically point to the new one:

NB. it'd be good to support a versioned permalink even for the latest docs (i.e. visiting the 2.21 link above should still work even now).
@huonw huonw added the enhancement New feature or request label Jun 9, 2024
@lilatomic
Copy link

I'm generally in favour of a "latest" link. I imagine it has benefits for Search, where the link can just point to the current version.

@lilatomic lilatomic reopened this Jun 9, 2024
@lilatomic
Copy link

Oh no I have so much power now, I can accidentally close issues when I hit the wrong shortcut D:
The linked thread talks to the downside to a "latest" link is that, when pages are renamed/consolidated, there's dead link. (To a lesser extent, this also happens with headings.) The thread mentions that we can configure redirects in the markdown, which I think is a good enough solution

@sureshjoshi
Copy link
Member

I slightly prefer the "no-version" approach that Docusaurus uses, as it's marginally easier to read - but mostly because we also have docs on main and also the beta docs - so in that case, "latest" has mild ambiguity - in that it actually means "latest stable release".

Screenshot 2024-06-07 at 09 35 54
Screenshot 2024-06-07 at 09 35 43

But, a gust of wind could sway me to any of the other variants - as any implementation of this feature would make me happy!

@copart-jafloyd
Copy link

stable would be a better term than latest. I've seen docs where "latest" refers the devel version...

cburroughs added a commit that referenced this issue Aug 27, 2024
@cburroughs
use friendly "semi-stable" urls for key versions
525bc48 
Currently all of the versioned docs have the explicit version in the
url.  This has the virtue of being
[cool](https://www.w3.org/Provider/Style/URI) but has some awkwardness
in practice.  For example if one links to
https://www.pantsbuild.org/2.18/docs/using-pants/using-pants-in-ci
from another webpage it will eventualy end up with the 'no longer
maintained' banner.  It isn't super fun to update every internal/wiki
link every 6 weeks for a release.

This change introduces some "semi-stable" urls for key versions:
 * `prerelease`: The latest prerelease
 * `dev`: aka `main` aka "trunk"
 * `stable`: The most recent stable release

Redirects ensure that the versioned urls also work.

As an example, right now:

`/stable/docs/using-pants/using-pants-in-ci` is the doc for `2.21` and
`/2.21//docs/using-pants/using-pants-in-ci` redirects to there.  After
the next release, `/stable/docs/using-pants/using-pants-in-ci` will be
for `2.22` and `/2.21/docs/using-pants/using-pants-in-ci` will keep
pointing to the `2.21` content.

I think this is reasonable compromise of easy of use with permanence.

FWIW the Offical Docusaurus position seems to be to prefer server side
redirects facebook/docusaurus#9049 but as
far as I can tell that isn't an option for GitHub Pages.

ref #221
@cburroughs cburroughs mentioned this issue Aug 27, 2024
Merged
@cburroughs
Copy link
Contributor

I'm gong to leave this opened for now as a marker for any followup and eventually supporting both (/stable and /the-version-num) urls like the Rust docs (if docusaurus makes that easier).

cburroughs added a commit that referenced this issue Sep 4, 2024
@cburroughs
use friendly "semi-stable" urls for key versions (#256)
6136389 
Currently all of the versioned docs have the explicit version in the
url. This has the virtue of being
[cool](https://www.w3.org/Provider/Style/URI) but has some awkwardness
in practice. For example if one links to
https://www.pantsbuild.org/2.18/docs/using-pants/using-pants-in-ci from
another webpage it will eventualy end up with the 'no longer maintained'
banner. It isn't super fun to update every internal/wiki link every 6
weeks for a release.

This change introduces some "semi-stable" urls for key versions:
 * `prerelease`: The latest prerelease
 * `dev`: aka `main` aka "trunk"
 * `stable`: The most recent stable release

Redirects ensure that the versioned urls also work.

As an example, right now:

`/stable/docs/using-pants/using-pants-in-ci` is the doc for `2.21` and
`/2.21//docs/using-pants/using-pants-in-ci` redirects to there. After
the next release, `/stable/docs/using-pants/using-pants-in-ci` will be
for `2.22` and `/2.21/docs/using-pants/using-pants-in-ci` will keep
pointing to the `2.21` content.

I think this is reasonable compromise of easy of use with permanence.

FWIW the Offical Docusaurus position seems to be to prefer server side
redirects facebook/docusaurus#9049 but as far
as I can tell that isn't an option for GitHub Pages.

ref #221
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@cburroughs @huonw @sureshjoshi @lilatomic @copart-jafloyd