Clarify documentation branching workflow in Git guide

[iddocohen]

Expanded the git workflow guide to clarify how documentation updates should branch and land docs/docs/development/git-best-practices.mdx.

Now calls out release branches alongside stable/develop, restores the original release checklist ordering, and adds a dedicated “Documentation branching workflow” section that explains when doc fixes should fork from stable versus develop.

@ogenstad @petercrocker Please let me know if I should add more. Please note, I kept it in develop branch, as I am not sure when this info should or should not become live for now.

Summary by CodeRabbit

Release Notes

• Documentation
  • Enhanced Git best practices documentation with new Release branches section covering release flow and synchronization.
  • Added comprehensive Documentation branching workflow guidance for different documentation scenarios including minor fixes, release-specific docs, and upcoming features.
  • Included detailed sync process for merging latest changes between stable and development branches.

[coderabbitai]

Walkthrough

The git best practices documentation was updated to include guidance on release branch management and documentation workflows. A new Release branches subsection was added describing the release-x.y flow and synchronization via automation. A Documentation branching workflow section was introduced with three subsections covering minor docs fixes, docs work on release branches, and future feature documentation. A corresponding documentation branching workflow block was added to the PR review process section. Additionally, a Regular sync process subsection was added describing steps to synchronize latest changes from stable into develop.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding clarification to documentation branching workflow in the Git best practices guide.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[ogenstad]

I'm not sure how much information we have to include here, but the release-x.y branches will regularly be brought back into develop to ensure that develop is also up to date.

So when we create a release branch we have a bot that will open PRs (for example #7611). If we don't have a release branch these PRs will be merged directly from stable into develop. When we create a release branch, which is typically as soon as there's development ongoing for both the upcoming release but also for the one after that (which we have now as work is ongoing both for Infrahub 1.5 and Infrahub 1.6, we'll see the same for 1.6 and 1.7). Once a release branch is created we update the bot so that the workflow is instead:

• stable -> release-1.5
• release-1.5 -> develop

Then when it's time for release it will be as you write above that the release branch is merged into stable and then brought back into develop, however at that time develop should still mostly be up to date.

[ogenstad]

We can add a line here stating that for features developed within a release branch the PRs for the docs should target that release branch.

[iddocohen]

Thanks for clarifying it further. Added more clarification in the documentation based on the feedback.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/docs/development/git-best-practices.mdx (1)

54-62: Close the code fence before the callout text.

The code block at line 54 is not properly closed. There should be a closing ``` on line 61 before the "Important" callout at line 62.

Apply this diff to fix the markdown syntax:

 git pull
 git submodule update --init --recursive
 
+```
+
 **Important**: Always use `--recurse-submodules` when pulling to avoid submodule synchronization issues.

🧹 Nitpick comments (2)

docs/docs/development/git-best-practices.mdx (2)

152-154: Improve readability of the Release branches description.

Line 154 is dense and uses multiple semicolon-separated clauses. Consider restructuring to mirror the format of other branch definitions or add line breaks for clarity. This will make the automation flow and conditional fallback easier to scan.

Suggested refactor:

-**Release branches**:
-
-- `release-x.y`: Cut from `develop` during release prep, merged into `stable` and then back into `develop`; an automation bot keeps them in sync by continuously PR-ing `stable → release-x.y` and `release-x.y → develop` (or `stable → develop` when no release branch exists)
+**Release branches**:
+
+- `release-x.y`: Created during release prep when development is ongoing for multiple releases; merged into `stable` at release time and then back into `develop`.
+  An automation bot synchronizes changes by opening PRs: `stable → release-x.y → develop` (or directly `stable → develop` when no release branch exists).

---

286-305: New Documentation branching workflow section directly addresses the release-branch docs guidance.

This section clearly delineates three distinct scenarios (minor published-doc fixes, release-branch work, unreleased features) and provides actionable branching and targeting instructions. The guidance aligns well with the Release branches model introduced earlier and directly implements the feedback about docs PRs targeting release branches when features live on release-x.y.

The practical examples (e.g., docs/stable-doc-workflow) and rebase/cherry-pick guidance add clarity. Consider a subtle forward-reference to the Release branches subsection (e.g., "see Release branches section above") to help readers unfamiliar with the release model understand the context.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 154e317 and f04cc86.

📒 Files selected for processing (1)

• docs/docs/development/git-best-practices.mdx (3 hunks)

🧰 Additional context used

📓 Path-based instructions (5)

docs/**/*.mdx

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use Docusaurus markdown/MDX features in documentation

docs/**/*.mdx: How-to guides should begin title with "How to..." and follow the Diataxis How-to structure (intro, prerequisites, step-by-step, validation, advanced, related)
Use imperative, task-focused instructions in guides; avoid digressions
Topics should use titles like "About..." or "Understanding..." and follow the Diataxis Topics structure (concepts, background, architecture, mental models, connections, alternatives, further reading)
Define new terms on first use; prefer domain-relevant terminology; keep naming consistent with Infrahub UI/data model

Files:

• docs/docs/development/git-best-practices.mdx

docs/**/*

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Develop documentation in docs/, preview with invoke docs.build docs.serve, and validate with invoke docs.validate

Files:

• docs/docs/development/git-best-practices.mdx

**/*.mdx

📄 CodeRabbit inference engine (.github/instructions/documentation.instructions.md)

**/*.mdx: Structure documentation primarily as How-to Guides and Topics (explanations) following the Diataxis framework
Use a professional, approachable tone; avoid jargon unless defined; use plain language with technical precision
Write concise, direct, active sentences
Be informative over promotional; focus on explaining how and why
Maintain consistent, predictable structure across sections and documents
For Guides: use conditional imperatives (e.g., "If you want X, do Y")
For Guides: focus on practical tasks and problems, not tools
For Guides: address the user directly with imperative verbs (e.g., "Configure...", "Create...")
For Guides: keep focus on the specific goal; avoid digressions into explanations
For Guides: title in YAML frontmatter should clearly state the problem and begin with "How to..."
For Guides: include an Introduction stating the problem/goal, context, and what the user will achieve
For Guides: include a Prerequisites/Assumptions section listing requirements and prior knowledge
For Guides: provide step-by-step instructions with numbered steps; include code snippets/screenshots/tabs/callouts as needed
For Guides: include a Validation/Verification section with checks, example outputs, and potential failure points
For Guides: include a Related Resources section linking to relevant guides/topics/reference
For Topics: title in YAML frontmatter should clearly indicate the topic; consider starting with "About..." or "Understanding..."
For Topics: include an Introduction with overview, why it matters, and questions answered
For Topics: include sections for Concepts & Definitions
For Topics: include Background & Context (history, design rationale, constraints)
For Topics: include Architecture & Design details/diagrams when applicable
For Topics: include Mental Models (analogies/comparisons)
For Topics: connect to other concepts and integration points
For Topics: include Alternative Approaches with pros/cons where relevant
For Topics: include a Further...

Files:

• docs/docs/development/git-best-practices.mdx

**/*.{md,mdx}

📄 CodeRabbit inference engine (CLAUDE.md)

Lint Markdown/MDX files with markdownlint using .markdownlint.yaml

Files:

• docs/docs/development/git-best-practices.mdx

docs/!(node_modules)/**/*.{md,mdx}

📄 CodeRabbit inference engine (CLAUDE.md)

docs/!(node_modules)/**/*.{md,mdx}: Lint documentation prose with Vale
Ensure Vale style checks pass for documentation

Files:

• docs/docs/development/git-best-practices.mdx

🧠 Learnings (12)

📓 Common learnings

Learnt from: BaptisteGi
Repo: opsmill/infrahub PR: 7044
File: docs/docs/guides/change-approval-workflow.mdx:93-107
Timestamp: 2025-08-15T08:57:37.880Z
Learning: In Infrahub's change approval workflow documentation, the "Restricted Access" role intentionally includes `global:edit_default_branch:allow_all` permission despite being described as allowing edits only to branches other than default. This configuration is expected behavior according to the maintainers.

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Documentation generated for Infrahub must reflect its novel approach, providing clarity around new concepts and demonstrating integration with familiar patterns from existing tools like Git, infrastructure-as-code, and CI/CD pipelines

📚 Learning: 2025-07-22T08:13:56.198Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Documentation generated for Infrahub must reflect its novel approach, providing clarity around new concepts and demonstrating integration with familiar patterns from existing tools like Git, infrastructure-as-code, and CI/CD pipelines

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-08-21T11:04:26.357Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/instructions/documentation.instructions.md:0-0
Timestamp: 2025-08-21T11:04:26.357Z
Learning: Applies to **/*.mdx : Ensure content is accurate and reflects the latest Infrahub version

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-08-21T11:04:26.357Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/instructions/documentation.instructions.md:0-0
Timestamp: 2025-08-21T11:04:26.357Z
Learning: Applies to **/*.mdx : Assume readers know Git/CI/CD/YAML-JSON/IaC basics; do not assume prior Infrahub knowledge—introduce core concepts from first principles

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-07-22T08:13:56.198Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Applies to docs/**/* : Develop documentation in `docs/`, preview with `invoke docs.build docs.serve`, and validate with `invoke docs.validate`

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-07-22T08:13:56.198Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Applies to {CONTRIBUTING.md,SECURITY.md} : See `CONTRIBUTING.md` and `SECURITY.md` at repo root for policies

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-07-22T08:13:56.198Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Applies to docs/docs/guides/**/*.{md,mdx} : Write guides in `docs/docs/guides/`

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-08-21T11:04:26.357Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/instructions/documentation.instructions.md:0-0
Timestamp: 2025-08-21T11:04:26.357Z
Learning: Applies to **/*.mdx : For Guides: include a Related Resources section linking to relevant guides/topics/reference

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-08-21T11:04:26.357Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/instructions/documentation.instructions.md:0-0
Timestamp: 2025-08-21T11:04:26.357Z
Learning: Applies to **/*.mdx : For Topics: connect to other concepts and integration points

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-08-21T11:04:26.357Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/instructions/documentation.instructions.md:0-0
Timestamp: 2025-08-21T11:04:26.357Z
Learning: Applies to **/*.mdx : Structure documentation primarily as How-to Guides and Topics (explanations) following the Diataxis framework

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-07-22T08:13:56.198Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-22T08:13:56.198Z
Learning: Infrahub offers a central hub to manage the data, templates and playbooks that powers your infrastructure by combining the version control and branch management capabilities similar to Git with the flexible data model and UI of a graph database

Applied to files:

• docs/docs/development/git-best-practices.mdx

📚 Learning: 2025-08-21T11:04:26.357Z

Learnt from: CR
Repo: opsmill/infrahub PR: 0
File: .github/instructions/documentation.instructions.md:0-0
Timestamp: 2025-08-21T11:04:26.357Z
Learning: Applies to **/*.mdx : For Guides: include an Introduction stating the problem/goal, context, and what the user will achieve

Applied to files:

• docs/docs/development/git-best-practices.mdx

🔇 Additional comments (2)

docs/docs/development/git-best-practices.mdx (2)

311-335: Step-by-step sync process is clear and actionable.

The "Regular sync process" subsection provides concise, numbered instructions with clear bash commands for the common task of syncing develop with stable. The structure complements the more comprehensive "After a release" section that follows and maintains consistency with the guide's how-to style.

---

468-473: Further reading section is well-organized.

The added Proposed changes link fits logically within the Further reading section and provides relevant context on Infrahub's change management model, which complements the Git branching guidance.