Editing 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

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).