Show docs for latest stable release (not branch)

[chillu]

From @dhensby:

we are seeing more and more community complaints about the docs and the fact they track the 4.x branch (ie: unreleased code) over the latest stable release. in 3.x this means docs that talk about php 7.2, myslq SSL support and in 4.x it means things around public repo, app folder and so on.

We should inspect the repos to find out the latest tag for each release line (3.x and 4.x), and build docs from that.

Acceptance criteria

• Docs are pulled from the branch representing the most recent stable minor
• There is some automation so that when we release a new stable minor, the branch reference is updated.
• The same automation adds a new minor branch to the developer-docs repository
• The same automation updates the github action in the developer-docs repository

[GuySartorelli]

I expect this is something we'll look at when implementing silverstripe/silverstripe-framework#10215

[GuySartorelli]

We're moving the docs to a new module - I think we can handle this simply through branching strategies. We can keep the 4 branch as the "stable" branch.

Proposal:

• PRs will not get merged into 4 unless they represent updates to documentation that are relevant to the currently available stable release of Silverstripe CMS.
• PRs for documentation of features or functionality that has not yet been given a stable release can be in a future minor release branch
  • e.g. currently 4.11 is stable, and 4.12 is in the future. We would have a 4.12 branch in the new repository for PRs which include documentation for features that will not be available until 4.12.0 is released.
• When the new minor is given a stable release, the minor release branch is merged into 4 and a new future minor release branch is created for the next minor version.
• The future minor release branch will be the default branch. Each time we do a stable minor release, we update the default branch. This avoids having docs accidentally merged into 4 because PRs will target the future minor by default.

This is a departure from the branching strategy for our normal repositories, but I think it is a clean way to resolve this problem and doesn't require any changes to the logic used to fetch docs.

[emteknetnz]

I don't like the idea of having a different set of rules for branching on only this repo. It's such an automatic thing merging up the latest minor into 4 that we're bound to forget this and publish things early multiple times. Also, being non-standard it won't play nicely with any future 'automatic merge-up' tooling we put into place.

Seem like we could fairly easily just keep this in lockstep with framework (seems like that's already assumed) and then use the latest minor branch that has at least 1 corresponding tag on silverstripe/framework e.g. there's a 4.11.0 framework tag right now, so use the docs 4.11 branch.

It's pretty easy to get silverstripe/framework tag information from the github api using curl within github actions

Does that sound achievable? Will netlify let use dynamically define what branch to pull content from when we calls its API?

[GuySartorelli]

Fair concerns, I could see the different branching strategy being forgotten quite easily.

use the latest minor branch that has at least 1 corresponding tag on silverstripe/framework ... Will netlify let use dynamically define what branch to pull content from when we calls its API?

That's not really possible with gatsby-source-git (which is how we grab branches atm) from what I can see - we'd need to either look for or create an alternative Gatsby plugin or fork that 9ne and modify it to do that, or maybe add it as a custom build step if that's a thing that can even be done.

[emteknetnz]

What you linked to contains a branch plugin option - would it work if we got github actions to update gatsby-config.js on the default branch on push events to update this to the branch we want it to use?

We could get gihtub actions to do a straight commit, though for better auditing we could get it to do a pull-request here. We'd need to update the confluence release plan to say merge the pull-request

[GuySartorelli]

Yeah, that would work. For some reason my brain didn't consider that we can just update that config whenever we do a release lol

Not sure where GitHub actions comes into this though? Wouldn't we only change the config when we do a minor (or major) release?

[emteknetnz]

🤖 A U T O M A T I O N 🤖

If we don't have pull-requests it's fully-automated and won't be forgotten during release time (humans do forget things sometimes)

With a pull-request it's still prone to humans forgetting a step in the release plan, so you could easily argue the automation isn't worth the investment. The open-pr would still show up in rhino or a similar tool though

[GuySartorelli]

I still don't understand what will trigger the action or when.... but that's fine, that goes beyond what I need for right now. 👍
I like the idea of lockstepping the docs with releases and updating the branch we pull from to be the most recent stable minor.

[maxime-rainville]

Just clarifying what is being proposed for my dumb brain:

• We want to stop building the doc from the 4 branch and use the latest stable patch release branch (which would be 4.11 at time of writing).
• Which branch is the latest stable would be determined by a creating a robot that looks at which tag is the latest stable tag.

If my high level understanding is accurate, I'm fine with this.

[GuySartorelli]

We want to stop building the doc from the 4 branch and use the latest stable patch release branch (which would be 4.11 at time of writing).

Yes.

Which branch is the latest stable would be determined by a creating a robot that looks at which tag is the latest stable tag.

The exact mechanism used here isn't really important - it could just as easily be something added to cow. I think the salient point there is that there will be some automation so that when we do a new major/minor release of Silverstripe CMS, a new branch is created in the docs repo and the reference in this repo is updated to look at that new branch.

[GuySartorelli]

Added acceptance criteria to match what has been discussed.

[GuySartorelli]

This is done.