Skip to content

Clarify documentation branching workflow in Git guide #7621

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: develop
Choose a base branch
from
+26 −1
Open

Clarify documentation branching workflow in Git guide #7621

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ece4ee9
Added workflow for documentation commits
iddocohen Nov 10, 2025
f04cc86
Clarified documentation further
iddocohen Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 26 additions & 1 deletion docs/docs/development/git-best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,10 @@ Infrahub follows a structured branching model designed for stable releases and c
- `stable`: Production-ready code, protected branch, only updated via PRs
- `develop`: Integration branch for new features, default branch for development

**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)

**Feature branches**:

- `feature/description`: New features or enhancements
Expand Down Expand Up @@ -279,6 +283,27 @@ Follow these practices to ensure smooth code review and integration.
- Squash commits if needed
- Use merge commit for feature branches

## Documentation branching workflow

Use the branch that matches when the change must appear on https://docs.infrahub.app:

### Minor fixes to published docs

- Branch directly from `stable` (for example, `docs/stable-doc-workflow`) so the fix deploys as soon as the PR merges
- If you already authored the fix on `develop`, rebase or cherry-pick it onto a `stable`-based branch before opening the PR
- Target `stable` in the pull request

### Docs for work on a release branch

- When a feature (or its documentation) lives on an active `release-x.y` branch, create your docs branch from that same release branch (for example, `release-1.5`)
- Target the release branch in your PR so the docs ship with the release and flow back into `develop` via the automated sync
- Rebase on the release branch regularly to pick up stabilization commits

### Future or feature documentation

- Branch from `develop` for docs tied to unreleased features
- This keeps upcoming content out of `stable` until the feature is available
Copy link
Contributor

@ogenstad ogenstad Nov 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


## Bringing latest changes from stable into develop

Periodically sync `develop` with `stable` to incorporate fixes and releases.
Expand Down Expand Up @@ -445,4 +470,4 @@ git commit -m "temp: use local submodule changes"
- [Understanding Git repositories in Infrahub](../topics/repository.mdx) - Repository integration concepts
- [Backend development guide](../development/backend.mdx) - Setting up the development environment
- [How to connect external Git repositories](../guides/repository.mdx) - External repository setup
- [Proposed changes](../topics/proposed-change.mdx) - Understanding Infrahub's change management
- [Proposed changes](../topics/proposed-change.mdx) - Understanding Infrahub's change management