docs: document main/dev branching strategy

[rm3l]

Target branch

• I have verified this PR targets the correct branch (see branching strategy)

Description

Documents the main/dev branching model adopted in ADR 007:

• README.md: added branching model summary to the Contributing section
• docs/rhdh-local-guide/help-and-contrib.md: added "Branching Model" subsection with PR targeting tables; updated contribution workflow to branch from the correct upstream base (upstream/dev or upstream/main)
• .github/PULL_REQUEST_TEMPLATE.md: added "Target branch" section with a verification checkbox
• .github/workflows/test.yml: added dev to push/pull_request branch triggers

Which issue(s) does this PR fix or relate to

• Related to ADR 007 - Branching strategy for rhdh-local development

PR acceptance criteria

• Tests updated and passing
• Documentation updated
• Built-in TechDocs updated if needed. Note that TechDocs changes may need to be reviewed by a Product Manager and/or Architect to ensure content accuracy, clarity, and alignment with user needs.

How to test changes / Special notes to the reviewer

• Verify TechDocs render correctly in RHDH Local (restart container and check the Help & Contributing page)
• Verify PR template renders correctly when opening a new PR
• Verify CI triggers on PRs targeting dev

[rm3l]

A separate PR will be created to update the CI side (also need some updates to the nightly job).

[rhdh-qodo-merge]

PR Summary by Qodo

Document main/dev branching model in contributing docs and PR template

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Document the main/dev/release branching model and PR targeting guidance in TechDocs.
• Add a PR template checkbox prompting authors to confirm the correct target branch.
• Configure Renovate to open dependency update PRs against dev by default.

Diagram

graph TD
  U(["Contributor"]) --> T["PR template"] --> D{"Choose target"} --> G["Contrib guide"] --> B["Git branches"]
  R["README.md"] --> G
  N["renovate.json"] --> B

  subgraph Legend
    direction LR
    _usr(["Actor"]) ~~~ _file["File/Doc"] ~~~ _dec{"Decision"}
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Enforce target branch via GitHub Action

• ➕ Prevents incorrect targeting automatically (fails PR checks)
• ➕ Reduces reliance on authors reading docs/templates
• ➖ Needs ongoing rule maintenance as branch policy evolves
• ➖ Can create friction/false positives for edge cases (backports, mixed changes)

2. Add branch-protection + PR rules (repository settings)

• ➕ Centralized enforcement without code changes
• ➕ Can require specific checks/labels per target branch
• ➖ Limited expressiveness compared to custom logic
• ➖ Harder to version-control and review policy changes

3. Split Renovate config per branch (or preset)

• ➕ More granular control over dependency flows (dev vs release branches)
• ➕ Can apply different update policies per branch
• ➖ More configuration complexity
• ➖ Harder to reason about a single source of truth for Renovate behavior

Recommendation: The current approach (docs + PR template prompt + Renovate default base branch) is the right first step: it’s low friction and makes the policy discoverable where contributors act. If mis-targeted PRs remain a problem, consider adding a lightweight GitHub Action to enforce/validate branch targeting rules.

Files changed (4) +50 / -3

Documentation (2) +34 / -3

README.mdSummarize main/dev branching model in Contributing section +6/-1

Summarize main/dev branching model in Contributing section

• Expands the contribution blurb to describe what 'main' and 'dev' represent and when to target each. Adds a pointer to the built-in contributing guide for full details.

README.md

help-and-contrib.mdAdd Branching Model guidance and correct workflow base branches +28/-2

Add Branching Model guidance and correct workflow base branches

• Adds a Branching Model subsection with tables for branch purpose and PR targeting guidance, plus a brief description of release branch flow. Updates the contribution workflow examples to branch from 'upstream/dev' for next-release work or 'upstream/main' for version-independent fixes.

docs/rhdh-local-guide/help-and-contrib.md

Other (2) +16 / -0

PULL_REQUEST_TEMPLATE.mdAdd target-branch verification section with branching-model link +13/-0

Add target-branch verification section with branching-model link

• Introduces a new "Target branch" section explaining the main/dev/release model and adds a checkbox for authors to confirm they targeted the correct branch. Links directly to the contributing guide’s Branching Model section via a blob/HEAD URL.

.github/PULL_REQUEST_TEMPLATE.md

renovate.jsonDefault Renovate base branch to dev +3/-0

Default Renovate base branch to dev

• Configures Renovate to open update PRs against the 'dev' branch by setting 'baseBranches' to 'dev'. This aligns dependency updates with the next-release development flow.

renovate.json

[rhdh-qodo-merge]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Context used

✅ Cross-repo context

  Not relevant to this PR: redhat-developer/rhdh

  Not relevant to this PR: redhat-developer/rhdh-plugins

1. Upstream checkout fails ✓ Resolved 🐞 Bug ≡ Correctness

Description

The contribution workflow instructs creating a branch from upstream/dev or upstream/main
immediately after adding the upstream remote, but it never fetches that remote, so fresh clones
may not have those remote-tracking refs and the checkout command will fail. This breaks the
documented setup flow for new contributors.

Code

docs/rhdh-local-guide/help-and-contrib.md[R133-136]

+# Create a branch from the correct base (see "Which branch should my PR target?" above)
+# For next-release work:
+git checkout -b feature/my-contribution upstream/dev
+# For version-independent changes:

Relevance

●●● Strong

Team commonly accepts fixes preventing broken contributor docs/onboarding (e.g., doc breakage fixes
accepted in PR #127).

PR-#127

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The snippet adds the upstream remote and immediately checks out from upstream/dev /
upstream/main without any git fetch upstream step in between, which can make those refs
unavailable locally.

docs/rhdh-local-guide/help-and-contrib.md[125-138]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The docs instruct `git checkout -b ... upstream/dev` and `upstream/main` right after adding the `upstream` remote, but don’t fetch from `upstream`. On a fresh clone, `upstream/dev` / `upstream/main` won’t exist locally and the command fails.

### Issue Context
This is in the “1. Prepare Your Environment” snippet.

### Fix Focus Areas
- docs/rhdh-local-guide/help-and-contrib.md[125-138]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Renovate ignores main branch ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

renovate.json restricts Renovate to only run against the dev base branch, but this PR’s
branching model docs explicitly classify GitHub Actions dependency updates as version-independent
changes that should target main. This will cause Renovate PRs to target the wrong branch (or leave
main without Renovate updates).

Code

renovate.json[R6-8]

+  "baseBranches": [
+    "dev"
  ]

Relevance

●● Moderate

No clear historical pattern on Renovate baseBranches vs main/dev model; only initial Renovate
onboarding seen (PR #137).

PR-#137

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Renovate is configured with baseBranches: ["dev"], while the README text added/updated by this PR
says GitHub Actions dependency updates (a common Renovate output) should target main.

renovate.json[1-9]
README.md[93-98]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Renovate is configured to only open update PRs against `dev`, which conflicts with the documented policy that version-independent changes (including GitHub Actions dependency updates) should target `main`.

### Issue Context
The README guidance is introduced/updated in this PR; Renovate will now not propose updates for `main`.

### Fix Focus Areas
- renovate.json[1-9]
- README.md[93-98]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

[zdrapela]

I'd consider creating an AGENTS.md (and CLAUDE.md with linked @AGENTS.md) file to specify this explicitly for AI tools. They should read the docs and README too, but they don't always keep it in context.

[rm3l]

Good point. An AGENTS.md file is being added in this other PR: #255
I can make sure to mention this in that PR. Does that make sense?

[zdrapela]

Okay, can be 👍

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[zdrapela]

LGTM