First experiment: stable-docs

[simonw]

I want to be able to publish updates to my /en/stable/ docs without needing to ship an entire release - for things like typo fixes and plugin directories.

My initial idea:

Have a stable-docs branch which is published by ReadTheDocs as the stable version.

Publish workflow force-updates that branch to be a copy of the tag that was just released

A file called _plugins.md lives in the repo and has the content for the plugins directory

Another workflow watches for changes to that file and automatically merges those changes into the stable-docs branch

So now… editing _plugins.md always goes live on stable-docs - and edits can be made on stable-docs to other stuff too, which will be over-written the next time a stable release is issued.

Would be good to have non-destructive merges into stable-docs when a release goes out just to avoid any chance of accidentally deleting edits made there that need to be preserved in history.

Also: any time you commit a change that modifies docs, tag it with !stable-docs and a workflow will automatically include that change in the current stable-docs branch.

[simonw]

Used GPT-4 to create an initial workflow for this: https://chat.openai.com/share/dbd19d7c-c022-4a11-9a52-7217316afd2a

[simonw]

The first run of that workflow created this branch: https://github.com/simonw/simonw-readthedocs-experiments/tree/stable-docs

[simonw]

https://readthedocs.org/dashboard/simonw-readthedocs-experiments/advanced/ has the default settings:

It's not giving me a "stable" option yet, maybe I need to ship a release?

[simonw]

Here's what that release did: https://github.com/simonw/simonw-readthedocs-experiments/actions/runs/5918859742/job/16048570940

No need for it to update the branch since there were no changes to it yet.

[simonw]

OK, ReadTheDocs noticed the release and created a stable version:

Now settings gives me the option to switch to that, which I'll do now: https://readthedocs.org/dashboard/simonw-readthedocs-experiments/advanced/

https://simonw-readthedocs-experiments.readthedocs.io/ now redirects to https://simonw-readthedocs-experiments.readthedocs.io/en/stable/

[simonw]

That commit triggered an error: https://github.com/simonw/simonw-readthedocs-experiments/actions/runs/5918907110/job/16048660640

simonw-readthedocs-experiments/.github/workflows/stable-docs.yml

Lines 25 to 30 in 03344fb

	- name: Check if stable-docs branch exists
	run: |
	if ! git rev-parse --verify stable-docs > /dev/null 2>&1; then
	git checkout -b stable-docs
	git push -u origin stable-docs
	fi

[simonw]

I think this test found that stable-docs did not exist even when it does:

if ! git rev-parse --verify stable-docs > /dev/null 2>&1; then

[simonw]

OK, that worked - the commit now skips the branch creation bit, but doesn't do anything else.

Next I'll test mentioning !stable-docs in a commit and see what happens.

[simonw]

No, that didn't work:

[simonw]

The thing I'm looking for here is to update stable-docs with the changes from the new commit.

But... I only want the docs/ changes. So I need a way of saying "cherry-pick changes from this commit that affect docs/ and apply those".

This might work: https://chat.openai.com/share/e4605046-d9e9-4fb6-838a-d0653670bbff

git show COMMIT_HASH -- docs/ > commit.patch
git apply commit.patch
git add docs/

I tested this and git show HASH --docs does indeed only return the diff for the bits that affect docs/.

[simonw]

[simonw]

OK, empty patches are now handled.

[simonw]

That didn't quite work:

[simonw]

Why did it create a new branch? It was supposed to use the origin/stable-docs branch.

[simonw]

Oops, "No changes to docs/ in this commit." - because I edited the README not something in docs/.

[simonw]

Looks promising: https://github.com/simonw/simonw-readthedocs-experiments/actions/runs/5921022485/job/16053032053

It triggered a build: https://readthedocs.org/projects/simonw-readthedocs-experiments/builds/

Those cancelled are what happens when you push a new commit before latest has finished building the last one.

[simonw]

https://simonw-readthedocs-experiments.readthedocs.io/en/stable/ now shows:

Despite the 0.2 tag not containing that: https://github.com/simonw/simonw-readthedocs-experiments/blob/0.2/docs/index.md

[simonw]

I think this might be working!

[simonw]

https://simonw-readthedocs-experiments.readthedocs.io/en/latest/ now has the 3 page docs site.

[simonw]

If I edit three.md with !static-docs I expect the /en/stable/ site will gain a page three but will NOT update the index as I didn't touch it in that commit.

[simonw]

No that didn't trigger the step:

[simonw]

That didn't run either. This if condition is failing for some reason:

simonw-readthedocs-experiments/.github/workflows/stable-docs.yml

Lines 41 to 47 in 2efb26d

	- name: Handle Commit to Main
	if: contains(github.event.head_commit.message, '!stable-docs')
	run: |
	git fetch origin
	git checkout -b stable origin/stable
	# Get the list of modified files in docs/ from the current commit
	FILES=$(git diff-tree --no-commit-id --name-only -r ${{ github.sha }} -- docs/)

[simonw]

Because I spelt it !static-docs and not !stable-docs!

[simonw]

That had the expected effect:

• It triggered the GitHub Actions step, which copied the contents of three.md over to the stable branch (because that file had changed in the commit)
• Which triggered a ReadTheDocs build
• Now https://simonw-readthedocs-experiments.readthedocs.io/en/stable/ still shows the previous page (no table of contents) - but https://simonw-readthedocs-experiments.readthedocs.io/en/stable/three.html DOES exist because that file was copied into the branch.

[simonw]

A new release should replace stable entirely.

[simonw]

That worked. https://simonw-readthedocs-experiments.readthedocs.io/en/stable/

I think this is done! Need to write it up as a TIL and maybe put it into production for LLM.

[simonw]

No it looks like we DO need that bit I removed in 1f25cfa

[simonw]

Yeah that works again, the fetch-depth: 0 is necessary. 261aeb9

[simonw]

This is now running in https://github.com/simonw/llm