Website out of date

[justsml]

Hi @mjackson and maintainers 👋

The current website looks out of date.

I noticed because I was working on content for my Open Source Workshop, and I want to use my PRs #6410 #6431 to show how welcoming & streamlined contributing can be (even to large projects.) ❤️

Turns out, I forgot to ever check if the website got updated 🤦‍♂️ oops. 😹

Now my OSS workshop slide "Are we 'done' yet?" gets a caveat:

1. PR Merged? Congrats! You're done! *

<small>* Check release schedule, and any related website/docs.</small>

(Btw, this might be related to #5944.)

[pshrmn]

Yeah, I think the answer is that "it's complicated". As I mentioned in that other issue, the ideal approach would be to keep dev code (including dev docs) in a separate branch.

For the time being there isn't a whole lot that we can do, but hopefully 4.4 comes out soon, and pending website changes get pushed out, and then maybe we can look into a different setup.

[justsml]

I understand. :)

Can I help with the process/plan?

What kind of deploy process exists? CI/CD? Manual?
Version/branch locked? Do you want to maintain old versions of docs? Only for major versions? In subfolder, like /docs/v2/api for v2? /docs/api/ for stable?

[pshrmn]

The current deploy process happens by pushing to the website branch. Michael actually did that in the last couple days, so I think that your changes should be live. (That said, there seems to be some CSS issue with code blocks that are pushing them to the right edge of the screen, but I haven't looked into the cause.)

I think that the website can get away with only documenting the latest version of packages, but only because old versions can be viewed on GitHub (assuming we have proper tags to make lookup easy). That is how the pre-v4 docs exist.

I don't love how the docs are currently structured in the repo. I've seen multiple times where people are unsure how to submit a documentation PR because the docs are hidden away in the package directories. A docs folder in the root directory would be more obvious. I'm not certain what the motivation for the current layout is, so I can't say whether a PR that moves the docs would actually be accepted.

[justsml]

I proposed a fix for the code offset issue #6606

Would it make sense to propose certain PRs against website branch then? Or is that just build content?

I agree on the docs structure change. Though not critical... I can throw a PR together to improve the experience for those new to contributing, with the /docs folder convention?

[mjackson]

Sorry, this was my bad. I'd like for the website to always track the latest stable release, not master. So I reverted the website back to what it was for the 4.3 release. But then some other stuff was broken, so I re-deployed the changes in master.

I'd like to figure out a better strategy for branching moving forward, after 4.4.

[mjackson]

Closing this for now. Let's figure out a better strategy for moving forward next week.