Pre-release testing questions

[huonw]

I've done some testing in advance. It looks really nice. I suspect there's a bunch of known issues, that I'm observing here, but I haven't seen a todo list/plan so I'm just going to write them all down. This also ends up as a mega issue and we can break up a bit after initial triage.

Random grab bag of things I like a lot (not exhaustive 😄 ):

• looks good, loads fast! 🏎️
• switching versions with the version selector preserves the page (if possible), rather than switching to the intro page 🎉
• table of contents and deep linking that works on mobile ☎️
• it runs locally 💻
• automation for updates! 🤖
• git for blog and general website content!

Original discussion, now real issues

Here's some comments (numbers for reference, not priority/importance):

1. Redirects of unversioned URLs don't seem to work; is that expected?
   • versioned: original: https://www.pantsbuild.org/v2.18/docs/python, new: https://docs.pantsbuild.org/v2.18/docs/python, redirect: https://docs.pantsbuild.org/2.18.x/docs/python/python-overview (shows content ✅ )
   • unversioned: original: https://www.pantsbuild.org/v2.18/docs/python, new: https://docs.pantsbuild.org/docs/python, not redirect and shows no content ❌
2. It looks like the heading fragments differ for some items, e.g. https://www.pantsbuild.org/v2.19/docs/reference-deploy_jar#coderesolvecode links to the resolve field specifically, while the redirect https://docs.pantsbuild.org/2.19.x/reference/targets/deploy_jar#coderesolvecode does not. Can we run client side JS easily (as part of the redirect)? If so, I guess we could replace codeXYZcode with XYZ, and maybe that handles most cases?
3. Somewhat related to the above, a "404" shows the menu structure but no actual content: https://docs.pantsbuild.org/xyz/abc. Is that expected?
4. The blog only seems to have 5 posts? http://docs.pantsbuild.org/blog (No, it's just the recent posts in the sidebar)
5. It seems a bit confusing for users to split the long-form text ("Docs") and detailed API descriptions ("Reference") into separate categories as they are: if I'm looking for how to learn something, I'd be hoping that everything I need is easy to find. Alternatives:
   • Include the reference sections in the sidebar for the docs view (maybe with a divider, if that's possible), but still have a direct link to it in the headings. That is, these things could be after "Tutorials - Coming soon"
     
   • If that doesn't work great, just have a link to "Reference" at the end of the Docs sidebar too, and a link to "Docs" in the "Reference" sidebar. (I.e. repeating links from the header, but in the place users might be looking)
6. The current 2.19.x reference docs show a TOML snippet, e.g. https://www.pantsbuild.org/v2.19/docs/reference-add-trailing-comma, but the new ones don't show this https://docs.pantsbuild.org/2.19.x/reference/subsystems/add-trailing-comma . Is that expected?
7. 1.30 is not marked as deprecated on the current docs, but doesn't appear to be preserved and redirects don't work. Are we just giving up on 1.30 entirely? e.g. https://www.pantsbuild.org/v1.30/docs -> https://docs.pantsbuild.org/v1.30/docs
8. Items in the sidebar seem be sorted alphabetically, but I think there's more meaningful order than that, e.g. for "Getting started", compare old (first) vs. new: the order in which people go through these matters! (There's other examples too)
   
9. Tweaks to the docs syncing automation:
   • It'd be good to assign reviewer(s), or else the doc update PRs would be easy to get lost. Suggestion: have the workflow dispatch take user name(s), and then if we have the release CI from the pants repo trigger this one, it can insert the release manager.
   • Can we include a link to the releases tag page in the PR, so that someone looking at it can more easily confirm what's included etc.?

Small things (just noting to have them written down, I could definitely fix them myself too, but I'm in "review" mode, not "code" mode):

1. Maybe we could just remove the "search coming soon" text completely: it gives me geocities vibes, where everything was always 🚧 under construction 🚧/coming soon and never actually did 😄 Once we have search, we can then just restore it.
2. "Whos Hiring?" in the footer should be "Who's Hiring?"
3. There's two levels of expanders for "Getting started": https://docs.pantsbuild.org/2.18.x/docs/getting-started/getting-started
   
4. The reference listing page for goals etc. seems to have large cards for each item, all with content ---. Is it possible to switch to either switch to a (denser) plain list, and/or put real content in those cards? https://docs.pantsbuild.org/2.18.x/reference/goals
   
5. (Why Node 18.0.0? AIUI, Node 20 is the most recent LTS?)
6. The README instructions didn't work for me, e.g. there's website/ directory for cd website, running npm start can't find docusaurus, I tried installing deps with npm ci but that failed too... probably because this is a yarn project? yarn start seemed to work
7. What would it take to have pants orchestrate this repo? 🤔
8. What's the difference between the docs/ and versioned_docs/ subdirectories?13.

Questions that I don't know if they should be issues:

1. Why Node 18.0.0? AIUI, Node 20 is the most recent LTS and I imagine there's minor/patch releases of Node 18 that might be relevant?
2. What would it take to have pants orchestrate this repo? 🤔
3. What's the difference between the docs/ and versioned_docs/ subdirectories?
4. Do you have ideas about how we could get doc previews for pants changes both locally and on a PR?

[thejcannon]

1. Node 18 was what was preconfigured for me when I ran the scripts to set up the site (via docusaurus)
2. 🤷‍♂️
3. That's a docusuarus behavior. This page explains it. For us, docs -> main, versioned_docs/ -> release branches
4. Yes-ish. Not concrete enough to say anything, but a new GitHub action which "does everything we need" would likely work

[huonw]

1. Ah, cool
2. 🤷‍♂️
3. Great, thanks for the link.
4. Cool. I opened Do temporary/example deploys for PRs #28.

I think that's enough from this issue, closing!