Implement doc-building from branches

[normanrz]

This is a proof-of-concept for #271. Instead of having one main branch that contains the specs for all versions, there will be branches for each version. On each of these branches, there will be a spec folder that will be used to render the website. I think this will be a better way of organizing the versions. In particular, it will be possible to use git for diffs between versions.

This PR adds some (admittedly hacky) code to check out the branches in the sphinx build step. It moves the current 0.5 folder to spec. So, this could become the new main (or latest) branch to base new changes off of. If we want to move forward with this approach, we would need to actually create the version branches.

[github-actions]

Automated Review URLs

• Readthedocs
• render latest/index.bs
• diff latest modified

[joshmoore]

https://ngff--282.org.readthedocs.build/0.3/index.html (for example) at least does render! 😄

[joshmoore]

In testing this PR, I found there was a good deal of cleaning up needed with the symlinking strategy, and it still ultimately wanted branches or tags for each specification.

After checking it was ok with Norman, I've updated this PR to demonstrate a submodule strategy. Each of the branches (e.g., https://github.com/joshmoore/ngff-specifications/tree/0.5) was created via this script:

for x in 0.1 0.2 0.3 0.4 0.5;
do
    git checkout -b $x main
    git rm $(git ls-files | grep -vE ^$x)
    git mv $x/* .
    git commit -m "Prepare submodule"
done

Tags are the same as in ome/ngff. An alternative would be to use git subtree split -P but this leaves each of the branches not having a relationship to one another. This way the history remains intact. Moving forward, changes would be built off the same starting point, beginning with 0.5.0.

[sbesson]

In the spirit of preserving multiple versions of a reference document, using Git branches/tags vs folders are two usual representations. The choice is a balancing act between the pros/cons of each strategy.

Git submodules/subtrees are interesting way to provide an hybrid approach to provide a folder-based view to point at different repositories/branches. I only have practical experience with submodules so I cannot reasonably comment on the subtree alternative.

Is the idea to fully separate the specification sources into a separate ngff-specifications Git repository and have this repository including them via submodules? Or would these specifications live on separate branches of the same ngff repository with the main branch declaring them as submodules? I have never tried the latter and I hadn't considered it before, my only thought is whether this could lead to recursion concerns under some scenarios?

With regards to the original issue #271, my understanding is that the current workflow for working on new specification is the following

1. copy all documents from the latest released version e.g. 0.5 to a new folder e.g. 0.6.
2. commit these changes to have a starting point that is the last specification
3. make changes to 0.6/index.bs
4. changes compared to the 0.5 versions can be computed either by running diff -u 0.5/index.bs 0.6/index.bs or running git diff <original_commit> -- 0.6/index.bs
5. once merged, further amendments of the 0.6/index.bs can be reviewed using git diff -- 0.6/index.bs
6. in all cases, reviewing the changes against an older specification e.g. 0.4 requires the local diff command as above.

and the current changes would lead to the following workflow:

1. create a new 0.6 branch off the latest tag/HEAD of the 0.5 branch
2. optionally update the top-level submodule so that latest tracks the 0.6 branch
3. make changes to index.bs
4. changes compared to the 0.5 version can be computed using git diff 0.5 -- index.bs
5. moving forward, changes can be computed against earlier versions of the specification

It feels like the primary benefit of this approach are to have a single history for all versions of the main specification document. For contributors, reviewers and maintainers, it feels like this could lower the work of computing the differences between different versions. It would be interesting to have reviewers opinoins. A possible limitation might be if a new tag on a former branch e.g. 0.5.1 tag introduces conflicts. A separate issue that is independently of the technology/strategy is that large rewrites of entire sections of a specification document are simply hard to review.
Obviously the addition of submodules includes the requirement to track them and puts additional burden for the maintainers. Similarly separate branches can create confusion for contributors. In all scenarios, codifying the workflow above and dealing with those issues via documentation will likely be required.

[joshmoore]

Is the idea to fully separate the specification sources into a separate ngff-specifications Git repository and have this repository including them via submodules? Or would these specifications live on separate branches of the same ngff repository with the main branch declaring them as submodules?

I was thinking a separate repo, but you're right since they share a history having those just as additional branches would be possible.

[dstansby]

It's only one data point, but my experience with git submodules have been pretty universally confusing. So I would say going down the submodule route would have to have good reasons that outweigh that.

Having said that, if this means a split of this repository into:

• A repo for just the spec (markdown + JSON schema), that has branches for versions
• A repo for rendering the website, w/ submodules

I think this might be fine, because the average contributor doesn't need to worry about submodules.

I do think it might be possible to just use branching in this repo though - what's the blocker on just having a single copy of files (no folders) and branches for different versions of the spec? Then the workflow to release would be:

• create a new 0.6 branch off the main branch
• add a "0.6" tag on the 0.6 branch

The workflow to do a minor amendment to an existing version would be:

• modify the 0.6 branch
• add a "0.6.1" tag to do a new release
• merge the 0.6 branch into the main branch

The workflow to update the WIP verison would be

• modify the main branch

Perhaps I am being a bit naive, but this seems like a much simpler workflow that what is being proposed? What are the downsides of this? Perhaps that it's challenging to render all versions on one site (though it seems like @normanrz managed to achieve this?)

[d-v-b]

I agree with @dstansby that simpler is better for this kind of thing. IMO the simplest approach would be a linear history, but I'm guessing this was decided against early on? I would be curious to see the reasoning for that choice.

[joshmoore]

Perhaps that it's challenging to render all versions on one site (though it seems like @normanrz managed to achieve this?)

That code was never full functional. And the workarounds I started putting in place just kept getting more and more complex.

what's the blocker on just having a single copy of files (no folders) and branches for different versions of the spec?

For the main branch I think that is fairly straight-forward. Deleting the extraneous files as I did in the submodules could also be done on a branch here. I thought it would (slightly) violate the principle of least astonishment, but that's ok. The deletes from the branch would possibly make them less useful in practice, in which case, simply archiving the built HTML pages for the earlier versions would almost work as well.

I think this might be fine, because the average contributor doesn't need to worry about submodules.

nods certainly not for any of the website stuff. And on the flip side, for someone who really does want to modify the spec+json-schema and not the webpage, the new repo would be very targeted.

[dstansby]

Was using readthedocs built in versioning system considered, so instead of rendering all versions of the spec on https://ngff.openmicroscopy.org/, there are multiple versions of https://ngff.openmicroscopy.org/ (e.g. https://ngff.openmicroscopy.org/0.1, https://ngff.openmicroscopy.org/0.2 etc.)? That would work with a simple branch approach.

[joshmoore]

That would have worked with the original repo when it was only the specs but won't scale with the addition of the other pages here.

[normanrz]

Perhaps that it's challenging to render all versions on one site (though it seems like @normanrz managed to achieve this?)

That code was never full functional. And the workarounds I started putting in place just kept getting more and more complex.

To be fair, I only really hacked on it 1-2h until I saw it that it could work and then paused the work for feedback. Not sure the workarounds would require that much more maintenance than the submodule solution.

I think the submodule solution, as Josh is proposing here, is fine. I agree that submodules can be quite annoying if you have to interact with them a lot. The specs don't change that often, though.

With the specs in their own repo and the submodule linking, could we still have the website preview? I find that very useful for checking the rendering while authoring changes.