[Feature Request]: Pull content from a branch other than main/master

[lcawl]

Prerequisites

• I have searched existing issues to ensure this feature hasn't already been requested
• I have tested using the latest version of docs-builder

What problem are you trying to solve?

Our reference documentation generally comes from repos where main or master branches contain future work and the "current" work occurs in a numbered branch that changes over time.

If I understand correctly, our first flush of content came from the "current" URLs, which means it likely was derived from content in various numbered branches. But the resulting markdown files are being put into main/master branches.

If this is an accurate summary, and especially if we move forward with the idea of having both "current" and "next" documentation (irrespective of whether the latter is internal or public), I think we need to be able to configure which branches "current" and "next" are derived from.

Proposed Solution

IMO somewhere on the assembler side things we need to be able configure which branches to pull content from.

In the short term, this would enable us to pull the "current" reference content from the appropriate branches.
In the longer term, it should also enable us to generate "future" previews from the right branches too.

NOTE: This request does not apply to repos that have a single branch strategy, like docs-content, search-ui, etc. IMO if "current" and "next" docs are generated for those types of content, it's more likely to rely on feature flags

IMPORTANT: If we're doing to do this and assume that the "current" branch will change over time, it means (similar to how we're doing it currently for the OpenAPI docs), teams will need to be really clear about when changed behaviour is introduced and have thorough change logs, even if the content is generated. i.e. be really (consistently) clear in the way they use metadata and text to say when things are added, deprecated, discontinued, etc.

Examples and Research

For example, right now it might look like this:

Repo, reference content set	Current	Next
elasticsearch, all	9.0	main
cloud, hosted	ms-120	ms-121 or master (if "next" is internal) or ms-120 (if "next" is public)
cloud, ece	ms-105	ms-122 or master (if "next" is internal) or ms-105 (if "next" is public)
cloud-on-k8s, all	2.16	main
curator, all	8.0	master
ecctl, all	1.14	master
apm-agent-java, all	1.x	main
ecs-logging-java, all	1.x	main

Alternative Solutions

This is a nebulous kind of alternative, but theoretically if we don't want to pull from multiple branches, there's a path where we could automatically copy content from multiple branches in repo A into multiple folders in repo B and serve them from there. IMO this would be for a use case where we're having multiple sibling pages because the reference information is automatically generated and must continue to published as separate pages for each release.

Additional Context

No response

How important is this feature to you?

I think this has a big impact in the Cloud reference content in particular, since I don't think we want to go public with newly generated content in master (i.e. we're okay with what we migrated from current but not once it's re-generated). This assumption might change if the milestone strategy changes.

[bmorelli25]

Related-ish #46 (comment)

[bmorelli25]

I believe this was added in #713? @Mpdreamz to confirm.

[lcawl]

Exciting, I do see current property in src/docs-assembler/assembler.yml in #713

[lcawl]

Note that per discussion with @nastasha-solomon there might be something to consider with respect to how teams are generating their release notes. i.e. if they're currently updating their automation to generate the release notes in "main" and soon have to change that to use "9.0" branch instead we might need to think about the long-term impact to that content. I haven't delved into this content enough yet to understand all the implications except that there might be a ripple here.