Skip to content

How to choose the right branch #11208

Open
@greg0ire

Description

@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.20.x is "legacy patch"
  • 2.21.x is "legacy minor"
  • 3.3.x is "patch"
  • 3.4.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
Loading

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
Loading

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions