Difference between revisions of "Backporting"

From GNU Radio
Jump to navigation Jump to search
Line 44: Line 44:


If a change is applicable to the main branch, and is small, it is preferable to have a single PR submitted against "master".
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 tagged with "backport-to-A.B" to indicate that project maintainers should attempt to make a corresponding change
The PR can be tagged 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,
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.
or the backport may be shelved.

Revision as of 20:45, 27 February 2021

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
  • 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 tagged 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.