Skip to content

Update branching documentation to reflect merge flow #11227

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
sensei-hacker wants to merge 2 commits into
base: maintenance-9.x
Choose a base branch
from
+27 −21
Open

Update branching documentation to reflect merge flow #11227

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bc35a61
Update branching documentation to reflect merge flow
sensei-hacker Jan 5, 2026
1264da6
Remove redundant Master Branch section
sensei-hacker Jan 5, 2026
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
40 changes: 23 additions & 17 deletions docs/development/Development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ You can also perform the git commands using the git client inside Eclipse. Refe

## Branching and release workflow

INAV uses maintenance branches for active development and releases. The `master` branch receives merges from maintenance branches.
INAV uses maintenance branches for active development and releases. The `master` branch tracks the current version by receiving merges from the current version maintenance branch.

### Branch Types

Expand All @@ -145,10 +145,6 @@ INAV uses maintenance branches for active development and releases. The `master`
- New features that require coordinated firmware and configurator updates
- Changes here will be included in the next major version release (e.g., 10.0)

#### Master Branch

The `master` branch receives periodic merges from maintenance branches.

### Choosing the Right Target Branch

When creating a pull request, target the appropriate branch:
Expand All @@ -171,37 +167,47 @@ When creating a pull request, target the appropriate branch:
1. Development occurs on the current version maintenance branch (e.g., `maintenance-9.x`)
2. When ready for release, a release candidate is tagged from the maintenance branch
3. Bug fixes during the RC period continue on the maintenance branch
4. After final release, the maintenance branch is periodically merged into `master`
4. After final release, the maintenance branch is periodically merged into `master`, which is then merged into the next version branch
5. The cycle continues with the maintenance branch receiving new changes for the next release

### Propagating Changes Between Maintenance Branches
**Merge flow:** `maintenance-9.x` → `master` → `maintenance-10.x`

Changes committed to the current version branch should be merged forward to the next major version branch to prevent regressions.
### Propagating Changes Between Branches

Changes committed to the current version branch flow through master to the next major version branch.

**Maintainer workflow:**
- Changes merged to `maintenance-9.x` should be regularly merged into `maintenance-10.x`
- Changes in `maintenance-9.x` are merged into `master`
- Changes in `master` are then merged into `maintenance-10.x`
- This ensures fixes and features aren't lost when the next major version is released
- Prevents users from experiencing bugs in v10.0 that were already fixed in v9.x

**Example:**
**Merge flow:**
```bash
# Merge changes from current to next major version
git checkout maintenance-10.x
# Step 1: Merge current version to master
git checkout master
git merge maintenance-9.x
git push upstream master

# Step 2: Merge master to next version
git checkout maintenance-10.x
git merge master
git push upstream maintenance-10.x
```

**Why use master as intermediate step:** This keeps master synchronized with the current version, so if a contributor accidentally branches from master, they get current version code without breaking changes from maintenance-10.x.

### Example Timeline

Current state (example):
**Current state (example - during 9.x series):**
- `maintenance-9.x` - Active development for INAV 9.1, 9.2, etc.
- `master` - Mirror of maintenance-9.x (receives merges via merge flow)
- `maintenance-10.x` - Breaking changes for future INAV 10.0
- `master` - Receives periodic merges from maintenance branches

After INAV 10.0 is released:
- `maintenance-10.x` - Active development for INAV 10.1, 10.2, etc.
**After INAV 10.0 is released:**
- `maintenance-10.x` - Becomes active development for INAV 10.1, 10.2, etc.
- `master` - Now mirrors maintenance-10.x (via merge flow)
- `maintenance-11.x` - Breaking changes for future INAV 11.0
- `master` - Continues receiving merges

### Working with Maintenance Branches

Expand Down
8 changes: 4 additions & 4 deletions docs/development/release-create.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -320,11 +320,11 @@ gh api repos/iNavFlight/inav-configurator/git/refs -f ref="refs/heads/maintenanc

### Branch Usage

- **X.x bugfixes** → PR to maintenance-X.x
- **Breaking changes** → PR to maintenance-(X+1).x
- **Non-breaking features** → PR to master
- **Changes maintaining backward compatibility** → PR to maintenance-X.x (e.g., maintenance-9.x)
- **Breaking changes** (MSP protocol, settings structure) → PR to maintenance-(X+1).x (e.g., maintenance-10.x)
- **Master** → NOT a PR target (receives merges only)

Lower version branches are periodically merged into higher version branches (e.g., maintenance-9.x → maintenance-10.x → master).
Lower version branches are periodically merged into higher version branches (e.g., maintenance-9.x → master → maintenance-10.x).

## Hotfix Releases

Expand Down