How to choose the right branch

[greg0ire]

Picking a branch

Now that 3.0.0 is finally released, the situation might be confusing for you as a contributor if you need to pick a branch.

Here is a flow chart you may follow, and there is equivalent text below if you prefer.

Below, we use the following aliases for the branches:

• 2.19.x is "legacy patch"
• 2.20.x is "legacy minor"
• 3.1.x is "patch"
• 3.2.x is "minor"
• 4.0.x is "major"

flowchart TD
    A{Are you touching source code ?}
    A -->|Yes| B{Is this a bugfix / security fix ?}
    B -->|Yes| C{Does it apply to 2.x?}
    C -->|No| E[patch]
    C -->|Yes| D[legacy-patch]
    B -->|No| F{Is this a breaking change?}
    F -->|Yes| G[major]
    F -->|No| H{Is this a forward-compatibility improvement?}
    H -->|Yes| I[legacy-minor]
    H -->|No| J[minor]
    A -->|No| K{Are you touching markdown/rst files ?}
    K -->|Yes| C
    K -->|No| E

Fixes

Security fixes, and bugfixes should go to the lowest branch that they can affect (usually 2.18.x, 3.0.x for bugs that only affect ORM 3)

Deprecations

New deprecations can be added on 3.1.x. There should be a resolution of each deprecation in 4.0.x. Improvement to the existing forward-compatbility layer such as deprecations that should have been added in 2.x can be added to 2.19.x.

New features and refactorings

Those should usually go to 3.1.x with the exception of features that simplify the upgrade path. These may go to 2.19.

Breaking changes

Breaking changes must go to 4.0.x. Each breaking change PR must come with a deprecation layer counterpart PR to 3.1.x

Mapping

Merges up

Once your changes land on a branch, they need to be merged up to other branches unless you are contributing to the major branch. That's done by maintainers, following this flowchart:

flowchart TD
    A(legacy patch) --> B(legacy minor)
    A --> C(patch)
    B --> D(minor)
    D --> E(major)
    C --> D