Skip to content
Merged
Changes from all commits
Commits
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
109 changes: 103 additions & 6 deletions docs/development/Development.md
Original file line number Diff line number Diff line change
Expand Up @@ -107,11 +107,13 @@ The main flow for a contributing is as follows:
7. `git add <files that have changed>`
8. `git commit`
9. `git push origin my-new-code`
10. Create pull request using github UI to merge your changes from your new branch into `inav/master`
10. Create pull request using github UI to merge your changes from your new branch into the appropriate target branch (see "Branching and release workflow" below)
11. Repeat from step 4 for new other changes.

The primary thing to remember is that separate pull requests should be created for separate branches. Never create a pull request from your `master` branch.

**Important:** Most contributions should target a maintenance branch, not `master`. See the branching section below for guidance on choosing the correct target branch.

Later, you can get the changes from the INAV repo into your `master` branch by adding INAV as a git remote and merging from it as follows:

1. `git remote add upstream https://github.com/iNavFlight/inav.git`
Expand All @@ -125,10 +127,105 @@ You can also perform the git commands using the git client inside Eclipse. Refe

## Branching and release workflow

Normally, all development occurs on the `master` branch. Every release will have it's own branch named `release_x.y.z`.
INAV uses maintenance branches for active development and releases. The `master` branch receives merges from maintenance branches.

### Branch Types

#### Maintenance Branches (Current and Next Major Version)

**Current version branch** (e.g., `maintenance-9.x`):
- Used for backward-compatible changes
- Bug fixes, new features, and improvements that don't break compatibility
- Changes here will be included in the next release of the current major version (e.g., 9.1, 9.2)
- Does not create compatibility issues between firmware and configurator within the same major version

**Next major version branch** (e.g., `maintenance-10.x`):
- Used for changes that introduce compatibility requirements
- Breaking changes that would cause issues between different major versions
- 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:

**Target the current version branch** (e.g., `maintenance-9.x`) if your change:
- Fixes a bug
- Adds a new feature that is backward-compatible
- Updates documentation
- Adds or updates hardware targets
- Makes improvements that work with existing releases

**Target the next major version branch** (e.g., `maintenance-10.x`) if your change:
- Breaks compatibility with the current major version
- Requires coordinated firmware and configurator updates
- Changes MSP protocol in an incompatible way
- Modifies data structures in a breaking way

### Release Workflow

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`
5. The cycle continues with the maintenance branch receiving new changes for the next release

### Propagating Changes Between Maintenance Branches

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

During release candidate cycle we will follow the process outlined below:
**Maintainer workflow:**
- Changes merged to `maintenance-9.x` should be regularly 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

1. Create a release branch `release_x.y.z`
2. All bug fixes found in the release candidates will be merged into `release_x.y.z` branch and not into the `master`.
3. After final release is made, the branch `release_x.y.z` is locked, and merged into `master` bringing all of the bug fixes into the development branch. Merge conflicts that may arise at this stage are resolved manually.
**Example:**
```bash
# Merge changes from current to next major version
git checkout maintenance-10.x
git merge maintenance-9.x
git push upstream maintenance-10.x
```

### Example Timeline

Current state (example):
- `maintenance-9.x` - Active development for INAV 9.1, 9.2, etc.
- `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.
- `maintenance-11.x` - Breaking changes for future INAV 11.0
- `master` - Continues receiving merges

### Working with Maintenance Branches

To branch from the current maintenance branch instead of master:

```bash
# Fetch latest changes
git fetch upstream

# Create your feature branch from the maintenance branch
git checkout -b my-new-feature upstream/maintenance-9.x

# Make changes, commit, and push
git push origin my-new-feature

# Create PR targeting maintenance-9.x (not master)
```

When updating your fork:

```bash
# Get the latest maintenance branch changes
git fetch upstream

# Push directly from upstream to your fork (no local checkout needed)
git push origin upstream/maintenance-9.x:maintenance-9.x
```