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.

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

"Learn more" link on front page is hard-coded to 2.19, should be latest stable #174

Closed
huonw opened this issue Mar 10, 2024 · 1 comment · Fixed by #177
Closed

"Learn more" link on front page is hard-coded to 2.19, should be latest stable #174

huonw opened this issue Mar 10, 2024 · 1 comment · Fixed by #177
Assignees
Labels
enhancement New feature or request

Comments

@huonw
Copy link
Contributor

huonw commented Mar 10, 2024

In #171 / pantsbuild/pants#20648, we adjust the front page "getting started" link to not be dead, by hard-coding it to the current latest stable series: 2.19.

Once we release 2.20, this link should point to the /2.20/... page.


We have one page that computes a dynamic link using the latest version:

We try and make contributions easy. For example, you can suggest documentation fixes by clicking on the Suggest Edits link on any page. And you can report bugs by opening a [GitHub issue](https://github.com/pantsbuild/pants/issues). If you want to hack on the Pants codebase itself there is a <Link to={`/${versions[0]}/docs/contributions`}>helpful guide</Link>.

import { default as versions } from "@site/versions.json";
import Link from "@docusaurus/Link";

... <Link to={`/${versions[0]}/docs/contributions`}>helpful guide</Link>.

That links to the latest non-dev version (which could be an RC pre-release) not the latest stable version, so we may want to find a better way to do it (and wrap it up in a component? https://docusaurus.io/docs/markdown-features/react).

Preferably we retain link validity checking for it too (#66).

@huonw huonw added the enhancement New feature or request label Mar 10, 2024
@huonw huonw changed the title "Getting started" link on front page is hard-coded to 2.19, should be latest stable "Learn more" link on front page is hard-coded to 2.19, should be latest stable Mar 10, 2024
@huonw
Copy link
Contributor Author

huonw commented Mar 10, 2024

One way to address this might be to have a custom field storing the latest stable version, that components can access via useDocusaurusContext. This would centralise the logic around "stable versions" etc. to all happen in docusaurus.config.js.

@huonw huonw self-assigned this Mar 12, 2024
huonw added a commit that referenced this issue Mar 12, 2024
The goal here is to centralise the logic around versions, creating a
list of all the details about each version (e.g. full version number,
whether it's a pre-release or unmaintained etc.), that downstream
processing can reference directly rather than recompute. This, for
instance, eliminates the duplicated logic around which versions are
maintained.

The goal here is to make changes like #174 (and maybe #159) easier. This
PR doesn't/shouldn't change observable behaviour.

This also removes the explicit `disableVersioning` flag, since that
seems to require changing the contents of the `versions` map. Instead
the existing use of `onlyIncludeVersions` seems to do what's intended:
make dev builds faster. An `npm start` build takes about 10s both with
the old `disableVersioning` setting, or just relying on
`onlyIncludeVersions`.

This includes some cut-and-paste rearrangement too that makes the diff
harder to understand. The commits are individually reviewable.
huonw added a commit that referenced this issue Mar 12, 2024
…ge (#177)

This PR fixes #174 with a new `VersionedDocsLink` component that reads
the docusaurus config to determine what the latest stable version is.

It also adjusts the other dynamic link to the contribution guide to use
this. This link is changed from the latest RC versions (currently 2.20)
to the current `main` version (2.21), i.e. the absolute most up-to-date
version of the contribution guide, which seems most relevant to
contributors since they'll be starting in the `main` branch.

This has a few issues with the component due to
prettier/prettier#12209, which forces us into
a very long line on the `_index.mdx` page.

I'm unclear if a broken link will be detected or not.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant