Docs automation and v0.5.1

[ellistarn]

Tell us about your request
We recently cut v0.5.1, but decided to hold off on docs changes until we can sort out what to do.

What does a docs version bump look like?

• Preview is copied into a new docs folder with the name of the new version
• The Version selector is updated to
• All installation references in the docs should point to the latest version

Is there anything else?

How can we automate this?

I'd like for us to drive all of this behavior from make release. Eventually (though potentially out of scope) we could trigger this in response to a tag push using something like https://github.com/vsoch/pull-request-action.

Is it possible to have some sort of variable in hugo like version=v0.5.1 and then we can reference that variable anywhere in the docs so we don't have to do any nasty string parsing and keep our automation up to date with every place version is mentioned?

I'm open to other ideas on this.

Additional context
As part of this work, we should update the docs to v0.5.1.

Attachments
If you think you might have additional information that you'd like to include via an attachment, please do - we'll take a look. (Remember to remove any personally-identifiable information.)

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or "me too" comments, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment

[tuananh]

This is good. less manual stuff is better :) lemme research to see how other projects are doing it :)

[tuananh]

Is it possible to have some sort of variable in hugo like version=v0.5.1 and then we can reference that variable anywhere in the docs so we don't have to do any nasty string parsing and keep our automation up to date with every place version is mentioned?

there's site's params which is like custom global var for hugo https://gohugo.io/variables/site/#the-siteparams-variable

we define it in config.toml, write a custom shortcode for it because we can't reference site.params in markdown. and then we use the shortcode in markdown docs.

UPDATE: apprently, there's already a builtin shortcode for that param but if we use this, when we archive old release, we will have to change it back to old release version. maybe we can build it and store the static html version of the docs?

[tuananh]

open a PR here https://github.com/aws/karpenter/pull/925/files . it's a small step toward docs release automation.

what do you think @ellistarn @geoffcline

[tuananh]

Another approach that i can think of is: when we cut a release, we put it into a branch.

• this way, we don't have to maintain lots of folders in our content/en. there's only docs folder.
• it will simply the release process a lot. we just have to cut a release with git by git checkout -b release-0-5-2. this branch will live under a subdomain of netlify. eg: v0-5-2-docs.karpenter.sh.
• we update netlify to point production to latest release.

the manual steps we need to do

• add the branch name to branch deploy in netlify
  

• create new branch and push it

downsides

it may affect searching feature as i'm afraid it can only search from current version of the docs only :-/ need confirmations here.

wdyt? @ellistarn @geoffcline

[geoffcline]

I am disinclined to use subdomains, as it requires integrating with netlify to do releases (new netlify deployment for each release). I am working on making a 'lil script to handle making the new docs dir during the release process. I would be more inclined to do more complex work if pushing new docs versions was causing substantial issues or taking up too much time. Just my thoughts. Thanks, Geoffrey