maester365
🙏 Docs for unreleased features
Describe the feature
When adding new features, tests, breaking changes etc. any updated website docs are published immediately on merge, while the change may not reach stable version for a while.
A suggestion would be to use docs versioning to have a versioned v1/stable docs and using the root docs as a "Next/Preview".
On Maester stable release, update the "stable" version. There's some added maintenance when fixing errors, but depending on release cadence for minor version they could possibly stay in preview docs for a while.
Additional context
Example scenario: https://github.com/maester365/maester/pull/961#issuecomment-2952543454
This is a great idea @fflaten would you want to take this task upon you?
Things to remember:
- Built pipelines get way more complex, because most static web hosts need a complete version of all the files. And cannot handle a partial (eg.
v1/...) update. Meaning you need to generate both the stable and the latest preview docs and put them in folders. - At what point do we release the docs?
- At a new stable release, do we delete the
preview? Only to put it back if there is a new preview version?
Might look at it after PSConfEU.
-
Docusaurus builds all versions every time and handles routing. Basically same as https://docusaurus.io/docs/next but only next/canary and major versions to reduce complexity.
-
Initial thought was on stable GitHub release: trigger workflow to create a PR update/replace the stable/v1 version.
-
Keep. The root docs would always be canary/next/preview. After stable release they'd be equal a short while, but quickly start accumulating docs from new PRs.
According to the Docusaurus docs it just creates a copy of the current docs and puts it in a different folder.
I'm not sure if that is the best idea, with the current state of the repo (everything combined).
Maybe @merill has a great idea? What about maybe splitting the docs as well?
Had some time to create a proof of concept: https://github.com/fflaten/maester/tree/docs-preview
Didn't have time to check all links for versioning-compatible syntax, nor have I tested the workflow in actions, just commands individually.
So one of the things we do is generate the cmdlet docs based on the code in /src/powershell
How about we keep main as the dev branch and create a new branch called production
We can then have
main → publish to → preview.maester.dev + PowerShell Gallery -Prerelease
production → publish to → maester.dev + PowerShell Gallery
This way most of the build and actions can be identical and also let's us do patches in prod and merge back into dev. Thoughts?
Please NO new production branch!
Then it might be better to tag a release and have that publish for production (so the github action releasing it to powershell gallery will trigger if we create a tag like v1.x.x) and that can also be the trigger for the docs.
You then only have to change the url for the docs from the main branch to preview.measter.dev
And if we want to be fancy and all the versions are probably tagged, we could make a workflow that does:
- check-out main branch
- execute
npm run docusaurus docs:version preview - Move the docs to dist folder
- check-out latest tag
- copy the docs to the dist folder
- check-out whatever tags we want published
- execute
npm run docusaurus docs:version {tag} - copy to dist
- Build and publish docs
But I kind of like more what @merill is suggesting (with the changes above).
I think having more than preview and prod would be overkill for Maester. Most folks use the latest version anyway as part of their pipeline.
I do like the tags approach.
According to the Docusaurus docs it just creates a copy of the current docs and puts it in a different folder
Yes, but my idea was just to have a single "Stable" version. On a new GitHub release, we remove and recreate it (the GitHub workflow).
That way we all just writes docs and code, including auto-generated command ref, like today and it's always shown as preview docs.
On a new GitHub release (that you already create), the workflow promotes every change/addition/removal in docs to the "Stable" version and submits a PR (QA only).
No need for a subdomain, just a simple dropdown in the top navbar on desktop and sidebar on mobile. No need for branches and no repo bloat besides a single "Stable" copy of the docs-folder at all times. Basically no extra maintenance/burden.
Try my branch above in local dev to see it in action. 🙂 Even the "edit this page" on Stable will point you to /website/docs/.... (the preview version docs) so all manual edits go to "preview" first.
We'd only have to do extra work (manual copy/paste) if we need to fix a critical docs that can't wait for stable release (the user can always find it in Preview docs).
@fflaten Thanks. I checked this out.
This looks good and it also makes it easy for folks to switch between preview and stable from the page.
I like it. Would you like to submit this as a PR?
I believe we can add the workflow for stable docs publishing to run whenever we publish a new major version using the publish-module.yaml action.
@fflaten but does this copy the docs? And does that need to be checked in? Or can we script it?
So that each documentation file does not need copying? Having a copy is going to cause problems, people editing the wrong file, docs not being in place.
I mean the code and docs are already tagged, that could be used to gather the right docs:
main= preview- latest tag
vx.x.x= stable
If the docs copy are checked in, it needs commit after the tag. Which means that tag is not the complete version that is released.
It is a copy, yes.
We could merge docs in a website deployment workflow, but we'd still need a placeholder "Stable" version checked in to run docusaurus locally. I find that more confusing personally.
The alternative would be two separate deployments to different URLs as you've suggested earlier.
If the docs copy are checked in, it needs commit after the tag. Which means that tag is not the complete version that is released
Correct. Is that an issue for the website though? The released product is the module
If the docs copy are checked in, it needs commit after the tag. Which means that tag is not the complete version that is released
Correct. Is that an issue for the website though? The released product is the module
And I think that a tag should be the complete version at that moment. The docs should definitely be part of the released product. Maester would not exists if there was no Maester website. Let's say there is a user that found a bug following specific docs. I might want to go back to what those docs said, I want to check-out that tag and run npm run start
Can't we make a PowerShell script that creates the docs from the current repo? That accepts a tag for the stable version? So people who want to run the versioned docs locally they can, and we can use the same script to release the docs.
Generate-VersionedDocs -StableTag "v1.1.9"
In the end it is not my call I'm just trying to make the project work for everybody.
Come to think of it, it will be included in the tag.
The PoC used on release trigger, but as @merill suggested calling it inside publish-module workflow, we'll be able to update docs prior to creating the tag and release.
This sounds great. I've had some similar thoughts and questions but wasn't able to articulate them as well as you both did. Using tags more effectively and having versioned docs for each release will be very helpful!
This was a great idea. Are there any remaining questions or details to iron out?
I just submitted versioned Docusaurus docs in #1340. Open to any feedback! It's relatively easy to do and will be a nice win for users who want relevant docs.
This was a great idea. Are there any remaining questions or details to iron out?
Sorry, I've been fully occupied with work for a while.
My initial plan was a "on:released" workflow, but to include stable docs in git tag (as requested) we'd have to reverse the order: update docs, then release.
I just never got around to test if we could simply call a composite action or reusable workflow as an prior job/step in the publish-module-workflow, or split them. The main (publish) workflow needs to continue with the post-docs commit before git tag&release.
I just submitted versioned Docusaurus docs in #1340. Open to any feedback! It's relatively easy to do and will be a nice win for users who want relevant docs.
Thanks for continuing. 🙏 Be aware that versioning will accumulate in size and slow down build times.
That's why I suggested having a single "Stable" version, deleting and recreating it every time.
I agree with you on that. My thoughts are that we would want two versions: the latest "stable" release (e.g., 1.3.0) and the latest preview release (e.g., 1.3.126-preview). We should be able to fine tune the GitHub workflow to handle this automatically. If not, the process to update versions seems fairly straightforward.
I just submitted versioned Docusaurus docs in #1340. Open to any feedback! It's relatively easy to do and will be a nice win for users who want relevant docs.
Thanks for continuing. 🙏 Be aware that versioning will accumulate in size and slow down build times.
That's why I suggested having a single "Stable" version, deleting and recreating it every time.
Shoot, I'm sorry -- I didn't realize you already had a branch with this all set up already!
No worries, just a PoC. 😉
Feel free to borrow whatever you need if you want to follow the route of "Next" and "Stable" versions only.
No worries, just a PoC. 😉
Feel free to borrow whatever you need if you want to follow the route of "Next" and "Stable" versions only.
Ok! I trust you have more experience with this than I, so feel free to submit changes to my PR!
Thanks @SamErde for working on this and @fflaten for raising this originally.
While I initially liked seeing the version in the drop down when I saw Sam's demo, I remembered how I felt when I was learning NextJs and they showed newer versions. As a user I didn't want to be installing an older version if there was something new.
I feel adding a version in the top banner and then displaying Next will create some confusion and FOMO and they have no easy of figuring out how to get that version.
For new users coming to Maester, I really want to keep it simple and get them to the pit of success.
Some of the other issues we had to tackle is the multiple folders for each version, the automated changes to the docs and also commiting back into the repo (which we already do with the cmdlets and I want to avoid more of them).
Here's what I've done, let me know what you think.
I've updated Cloudflare to stop pulling from main for maester.dev, instead it monitors a new branch website-prod (sorry @svrooij Cloudflare doesn't support tags, if it did it would have been ideal).
Every time a new Production release is tagged in GitHub, a new workflow will delete the website-prod branch and create a new one off the current tag. This is how maester.dev will update itself.
The https://preview.maester.dev site will always build whenever there is a new commit to the repo. This will make it always show the latest version.
So this is the bit I've published in the site at https://preview.maester.dev/docs/contributing#contributing-to-maester-docs-and-blog-posts
Here's the summary
| Environment | URL | Branch | Update Trigger |
|---|---|---|---|
| Production | https://maester.dev | website-prod | New Maester module release |
| Preview | https://preview.maester.dev | main | Every commit to the main branch |
The only catch is for urgent doc changes or blog posts that can't wait till the next release.
The way to do this is to update the website-prod branch directly and merge (or duplicate) the changes into main. I don't think we will do this often.
So as an fyi, the current maester.dev site is now published off the tagged version in 1.3.0
On the whole I think we should force ourselves to do monthly releases to avoid this scenario of messing with the other branch.
I feel adding a version in the top banner and then displaying Next will create some confusion and FOMO and they have no easy of figuring out how to get that version.
I'll play devil's advocate for a moment. 🙂 As a user, being able to see documentation in one place (with an easy way to find the docs for the version that I use) feels like an ideal experience.
Note that the "Next" label can be changed to anything, such as "Preview 1.3.126" or "1.3.126 (preview)."
So this is the bit I've published in the site at https://preview.maester.dev/docs/contributing#contributing-to-maester-docs-and-blog-posts
The separate preview site does have multiple advantages, one of which is that it is a more comprehensive test of the publishing workflow than previewing changes on a local development server. It allows others to easily preview changes.
On the whole I think we should force ourselves to do monthly releases to avoid this scenario of messing with the other branch.
This does seem like the logical conclusion. It's a lot of work, but GitHub workflows can help with things like the change log and release notes. I have always recommended that people use the latest preview release because so many fixes and improvements come between production releases. A monthly cadence would essentially eliminate that problem.
Cheers. Thanks @SamErde for champioining this. I've merged the PR and it's live now.
I did comment out the workflow for major releases since there is more to do there. We need to delete the old version folder before generating the new one and update the version file etc...
For now I'll do it manually when we do major releases and once I know the exact steps I'll add it to a workflow for automation.
Great convo here, guys. Thanks for the suggestion, @fflaten! We should chat more about what an optimal workflow would look like between the automated/manual release cycles and the Cloudflare pages element. Finally taking the time to try it out revealed that some of my first impressions/assumptions were wrong about this feature. To clear up and wrap up this thread, a few basic things that I learned:
- Docusaurus versions don't rely on GitHub tags (although I'm sure you could build a relationship)
- Docusaurus doesn't copy the entire docs folder for every version, just the changes
- You can choose which versions to keep published, and can "tag' versions as current, unreleased (preview), or unmaintained (deprecated).
- It's relatively easy to setup and modify