ADR-006: Branching strategy for rhdh-local development by rm3l · Pull Request #18 · redhat-developer/rhdh-adr

rm3l · 2026-07-08T11:21:25Z

Summary

Proposes a dev branch strategy for rhdh-local to unblock next-release development (e.g., PR #256) while keeping main stable for end users
Documents three rejected alternatives (rotating default branch, early release branch, latest/next rename scheme) with Mermaid diagrams for each
Includes cherry-pick policy and honest trade-off analysis (merge complexity, divergence risk)

Test plan

Review ADR content for accuracy against current rhdh-local release process
Verify Mermaid diagrams render correctly on GitHub. Preview
Confirm cherry-pick policy aligns with team expectations
Validate with RHDH productization team that FF script changes are feasible

Assisted-by: Claude

Propose a `dev` branch strategy for rhdh-local to unblock next-release development while keeping `main` stable for end users. Assisted-by: Claude

GitHub's Mermaid renderer requires `gitGraph` (camelCase), not `gitgraph` (lowercase). Assisted-by: Claude

Add Slack link for PM requirement, clarify upgrade path for existing users, and improve phrasing in context section. Assisted-by: Claude

Clarify that changing the GitHub default branch does not break existing clones; the real issue is that main would need to carry unstable content. Assisted-by: Claude

Add release-1.10, release-2.2 branches and patch tags (v1.10.2, v2.1.1) to all diagrams to show the full branching strategy across multiple release cycles. Assisted-by: Claude

Add main merges for v2.1.1 and v2.2 GA, add v1.10.3 patch tag, extend dev to 2.3 work, and remove duplicate commit id text where a tag already shows the same version. Assisted-by: Claude

Shorten labels to reduce text overlap and add ★ default markers to Alt 1 and Alt 3 diagrams to clarify which branch is the default at each point. Assisted-by: Claude

Update Alt 1 diagram with release-1.10 as current default, add ★ default markers to Alt 1 and Alt 3, tighten Alt 2 rejection rationale, consolidate divergence negatives, add integration point positive, and trim outdated points. Assisted-by: Claude

Move v1.10.0 tag to release-1.10 branch with default marker, and lowercase "Alternatives considered" heading. Assisted-by: Claude

Interleave release-1.10 patch tags with dev/main 2.1 work to make it clear that maintenance releases happen in parallel with new development. Assisted-by: Claude

Use mainBranchName init config to show "main (default)" in diagrams where the default branch does not change. Assisted-by: Claude

Both the Decision and Alt 2 diagrams used mainBranchName config to rename main to "main (default)" but had no initial commit before the first branch statement, causing GitHub to error with "Current branch (main (default)) has no commits". Assisted-by: Claude

Alt 1: clarify that existing users would need to switch branches at each GA, defeating the simple "pull to upgrade" workflow. Alt 2: focus on the practical downside that the development target branch changes every release cycle, vs. a stable dev branch. Assisted-by: Claude

Assisted-by: Claude

Consistent with Decision and Alt 2 diagrams that label the default branch explicitly. Assisted-by: Claude

Assisted-by: Claude

gazarenkov

There is one important difference between "usual" flow and rhdh-local we need to emphasize (it may look obvious now):
We fix bugs right do not provide any bug-fix releases

gazarenkov · 2026-07-09T07:21:49Z

+
+**Cherry-pick policy**:
+- Version-independent changes (documentation, GitHub Actions dependency updates) can target `main` directly or be cherry-picked between `dev` and `main`
+- RHDH-specific or configuration changes remain on `dev` until the corresponding RHDH version is GA and the `release-x.y` branch is merged into `main`


What about bug fixes, are they classified as "RHDH-specific or configuration changes"?

I think it is important to mention (even if may look obvious) - we do not provide bug-fix releases?

Fixes just land on the corresponding branch and users git pull. It happened in the past that we needed to add some RHDH-Local-specific configuration changes to fix an issue in the release branch.

Not sure I get it, sorry, let me rephrase.

We suppose majority of local-rhdh users use main branch, right?
They clone and run it any time

So, I guess main branch should receive the fixes as soon as it is ready to merge, in contrast to releasing latest z-version?

Yes, most rhdh-local users would use the main branch. New users would indeed clone and run it, no issue for that.
But existing users (who already cloned main) cannot just git pull as they might get breaking changes, which might be problematic especially for the plugin development use cases.
While main and release-1.10 are "quite" similar (they point to the same stable RHDH version, which appears to be the latest 1.10 at this time), fixes are currently merged to main and cherry-picked into release-1.10 (or the other way around). But because 1.9 is still supported, the release-1.9 branch might also receive fixes if needed. So to me, yes, we do provide bug-fix releases.
Does that clarify?

gazarenkov · 2026-07-09T07:21:52Z

+**Cherry-pick policy**:
+- Version-independent changes (documentation, GitHub Actions dependency updates) can target `main` directly or be cherry-picked between `dev` and `main`
+- RHDH-specific or configuration changes remain on `dev` until the corresponding RHDH version is GA and the `release-x.y` branch is merged into `main`
+- Fixes to `release-x.y` branches should be cherry-picked to both `main` and `dev`


Do we need to maintain older releases?

I think so (example of discussion here). Besides trying out the latest stable release of RHDH locally, users also rely on RHDH Local for plugin development before moving to production. So they may stay on a specific release-x.y branch to develop plugins against that (supported) RHDH version.
I've added a few lines about that.

…eases - Add context that rhdh-local is also used for local plugin development - Clarify cherry-pick policy for bug fixes - Note that older release branches are maintained for plugin development Assisted-by: Claude

Assisted-by: Claude

- Remove "one release ahead" constraint on dev - Clarify release branch maintenance tied to RHDH support lifecycle - Remove incorrect Alt 3 claim about release branch creation timing Assisted-by: Claude

openshift-ci Bot added the do-not-merge/work-in-progress label Jul 8, 2026

ADR-006: Branching strategy for rhdh-local development

cbef9c1

Propose a `dev` branch strategy for rhdh-local to unblock next-release development while keeping `main` stable for end users. Assisted-by: Claude

rm3l force-pushed the feat/rhdh-local-branches-and-rhdh-versions branch from 51944a2 to cbef9c1 Compare July 8, 2026 11:23

rm3l added 4 commits July 8, 2026 13:24

Fix Mermaid gitGraph casing for GitHub rendering

2fade85

GitHub's Mermaid renderer requires `gitGraph` (camelCase), not `gitgraph` (lowercase). Assisted-by: Claude

Refine ADR-006 context and decision wording

ff17e07

Add Slack link for PM requirement, clarify upgrade path for existing users, and improve phrasing in context section. Assisted-by: Claude

Tighten Alt 1 rejection rationale

94a834d

Clarify that changing the GitHub default branch does not break existing clones; the real issue is that main would need to carry unstable content. Assisted-by: Claude

Expand Mermaid diagrams with multiple release cycles

dfa39c8

Add release-1.10, release-2.2 branches and patch tags (v1.10.2, v2.1.1) to all diagrams to show the full branching strategy across multiple release cycles. Assisted-by: Claude

rm3l force-pushed the feat/rhdh-local-branches-and-rhdh-versions branch 3 times, most recently from 9a8d3f5 to b175f41 Compare July 8, 2026 12:20

Polish decision diagram and remove redundant tag labels

3f15d4e

Add main merges for v2.1.1 and v2.2 GA, add v1.10.3 patch tag, extend dev to 2.3 work, and remove duplicate commit id text where a tag already shows the same version. Assisted-by: Claude

rm3l force-pushed the feat/rhdh-local-branches-and-rhdh-versions branch from b175f41 to 3f15d4e Compare July 8, 2026 12:22

rm3l added 10 commits July 8, 2026 14:28

Improve diagram readability and default branch markers

706d80f

Shorten labels to reduce text overlap and add ★ default markers to Alt 1 and Alt 3 diagrams to clarify which branch is the default at each point. Assisted-by: Claude

Fix Alt 1 diagram and minor heading adjustment

f3e311d

Move v1.10.0 tag to release-1.10 branch with default marker, and lowercase "Alternatives considered" heading. Assisted-by: Claude

Show concurrent patch releases in diagrams

31c502e

Interleave release-1.10 patch tags with dev/main 2.1 work to make it clear that maintenance releases happen in parallel with new development. Assisted-by: Claude

Label main as default in Decision and Alt 2 diagrams

9e953e3

Use mainBranchName init config to show "main (default)" in diagrams where the default branch does not change. Assisted-by: Claude

Clarify Alt 3 rejection: renaming main breaks existing clones

2bf266d

Assisted-by: Claude

Use 'latest (default)' branch name in Alt 3 diagram

844b96c

Consistent with Decision and Alt 2 diagrams that label the default branch explicitly. Assisted-by: Claude

Update ADR title casing and format

1ed6019

Assisted-by: Claude

gazarenkov reviewed Jul 9, 2026

View reviewed changes

rm3l added 3 commits July 13, 2026 11:34

Show release-1.10 patch merges to main in Decision diagram

4b82a39

Assisted-by: Claude

Refine ADR-006: dev constraint, release maintenance, Alt 3 rationale

a83da20

- Remove "one release ahead" constraint on dev - Clarify release branch maintenance tied to RHDH support lifecycle - Remove incorrect Alt 3 claim about release branch creation timing Assisted-by: Claude

rm3l marked this pull request as ready for review July 13, 2026 09:51

openshift-ci Bot removed the do-not-merge/work-in-progress label Jul 13, 2026

rm3l requested review from a team and gazarenkov July 20, 2026 09:52

rm3l added 2 commits July 21, 2026 13:37

Merge branch 'main' into feat/rhdh-local-branches-and-rhdh-versions

67d790f

Merge branch 'main' into feat/rhdh-local-branches-and-rhdh-versions

18596ed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

ADR-006: Branching strategy for rhdh-local development - #18

ADR-006: Branching strategy for rhdh-local development#18
rm3l wants to merge 21 commits into
redhat-developer:mainfrom
rm3l:feat/rhdh-local-branches-and-rhdh-versions

rm3l commented Jul 8, 2026 •

edited

Loading

Uh oh!

gazarenkov left a comment

Uh oh!

gazarenkov Jul 9, 2026

Uh oh!

rm3l Jul 13, 2026 •

edited

Loading

Uh oh!

gazarenkov Jul 23, 2026

Uh oh!

rm3l Jul 23, 2026 •

edited

Loading

Uh oh!

gazarenkov Jul 9, 2026

Uh oh!

rm3l Jul 13, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

rm3l commented Jul 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

gazarenkov left a comment

Choose a reason for hiding this comment

Uh oh!

gazarenkov Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

rm3l Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gazarenkov Jul 23, 2026

Choose a reason for hiding this comment

Uh oh!

rm3l Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gazarenkov Jul 9, 2026

Choose a reason for hiding this comment

Uh oh!

rm3l Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rm3l commented Jul 8, 2026 •

edited

Loading

rm3l Jul 13, 2026 •

edited

Loading

rm3l Jul 23, 2026 •

edited

Loading

rm3l Jul 13, 2026 •

edited

Loading