Backporting

This page is a work in progress

Maintained Versions

Primary development happens on the main branch (called "master"). This branch changes quickly. Core developers understand that incompatible changes may happen at any time, requiring changes to work in progress.

Users and packagers are usually more interested in stable branches, where compatibility can be assumed. GNU Radio will maintain the last two stable API-level branches. At the time of writing:

• 3.9 is the most recent stable branch, at v3.9.0.0 (TBD: 3.9 may be an interim branch, with 3.10 being the next stable branch)
• 3.8 is the previous stable branch, at v3.8.2.0

Only one release train will be supported for each branch. For example:

• v3.8.2.1 is released, fully compatible with v3.8.2.0.
• v3.8.3.0 is released, potentially requiring a rebuild. Support for v3.8.2.X is dropped.

In exceptional cases, such as frequent crashes in critical functionality, an effort will be made to update unsupported branches.

Backporting

Changes made to the main branch may be applied to stable branches if they fix a problem or add an important feature, do not affect intended compatibility, and developer time (project or external) is available. Examples of things that make good backports:

• Bug fixes for non-working or incorrect functionality
• Memory management fixes that will have a noticeable effect (crashes, leaks)
• Security fixes (not typically applicable to GR)

Some things that do not make good backports:

• Style changes, comment fixes (other than to correct documentation errors)
• API changes
• Optimizations, unless there is a large performance effect
• Dependency or build environment changes
• More correct use of C++, moving from boost to std

If in doubt, ask before doing significant work against a stable version. There are bound to be exceptions we haven't thought of.

Trivial Backports

If a change is applicable to the main branch, and is small, it is preferable to have a single PR submitted against "master". The PR can be labelled with "Backport-A.B" to indicate that project maintainers should attempt to make a corresponding change to the stable branches. If that process turns out to be not so trivial, the PR author may be asked to help with the backport, or the backport may be shelved.

Complex Backports

There are areas of the code where only a few people have the experience to make changes, or where a large effort will be needed. In this case, the PR submitter will submit backports as needed/desired for each supported branch.

Forward Porting of Bug Fixes

We would like to encourage bug fix contributions for stable branches, and do not want to require contributors to work with future versions of software in order to help out. It would be helpful if a PR for a fix noted whether the fix applies to future versions.

Maintainer Notes

PR commits should be rebased and squashed before they are merged to the main branch. This keeps commits:PRs 1:1, allowing for better traceability.

Back/forward ports should contain a single, self-contained change. Cherry picks should use -x to keep traceability to the original commit.

The PR for this port should reference the PR for the original commit.

Maintainer's signature is added to the backport (e.g., -s option to cherry-pick)

Example backport:

• git checkout maint-3.8
• Locate commit(s) for the PR to be backported
• git checkout -b backport/maint-3.8/PR_NUMBER
• git cherry-pick -x -s COMMIT_REF
• git push --set-upstream origin HEAD
• Create a PR against maint-3.8, with a reference to the original PR
• Handle same as any other PR against maint-3.8

Any procedure that gives the same result is fine. Original PR and backport PR will now have references to each other, since backrefs are created by Github. Backport commit has a reference to the original commit (-x option to cherry-pick).