From bc35a61b651d279a43787c3157fdc93f21e0c688 Mon Sep 17 00:00:00 2001 From: Ray Morris Date: Sun, 4 Jan 2026 23:44:54 -0600 Subject: [PATCH 1/2] Update branching documentation to reflect merge flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarify that the merge flow is: maintenance-9.x → master → maintenance-10.x This keeps master synchronized with the current version branch, so if contributors accidentally branch from master they get current version code without pulling in breaking changes from the next major version. Key changes: - Emphasize master is NOT a PR target (receives merges only) - Update merge flow documentation in both Development.md and release-create.md - Clarify backward compatibility vs breaking changes - Add maintainer workflow examples showing 2-step merge process --- docs/development/Development.md | 40 +++++++++++++++++++----------- docs/development/release-create.md | 8 +++--- 2 files changed, 30 insertions(+), 18 deletions(-) diff --git a/docs/development/Development.md b/docs/development/Development.md index de8fbdecbfe..266da312da6 100755 --- a/docs/development/Development.md +++ b/docs/development/Development.md @@ -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 @@ -147,7 +147,9 @@ INAV uses maintenance branches for active development and releases. The `master` #### Master Branch -The `master` branch receives periodic merges from maintenance branches. +The `master` branch receives periodic merges from the current version maintenance branch (e.g., maintenance-9.x). It serves as a mirror of the current version and a safety net - if a contributor accidentally branches from master, they won't pull in breaking changes from the next major version branch. + +**Master is NOT a target for pull requests** - contributors should target the appropriate maintenance branch. ### Choosing the Right Target Branch @@ -171,37 +173,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` + +### Propagating Changes Between Branches -Changes committed to the current version branch should be merged forward to the next major version branch to prevent regressions. +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 diff --git a/docs/development/release-create.md b/docs/development/release-create.md index ec362da0911..3d21a36f31d 100644 --- a/docs/development/release-create.md +++ b/docs/development/release-create.md @@ -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 From 1264da64f325698b8fcb8d2ce2a71be664107b56 Mon Sep 17 00:00:00 2001 From: Ray Morris Date: Sun, 4 Jan 2026 23:54:50 -0600 Subject: [PATCH 2/2] Remove redundant Master Branch section The 'Choosing the Right Target Branch' section already covers that master is not a PR target. Lead with what contributors should do rather than what they should not do. --- docs/development/Development.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/development/Development.md b/docs/development/Development.md index 266da312da6..59063ad89cc 100755 --- a/docs/development/Development.md +++ b/docs/development/Development.md @@ -145,12 +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 the current version maintenance branch (e.g., maintenance-9.x). It serves as a mirror of the current version and a safety net - if a contributor accidentally branches from master, they won't pull in breaking changes from the next major version branch. - -**Master is NOT a target for pull requests** - contributors should target the appropriate maintenance branch. - ### Choosing the Right Target Branch When creating a pull request, target the appropriate branch: