How to choose the right branch

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.7.x is "patch"
• 3.8.x is "minor"
• 4.0.x is "major"

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

Security fixes and PHP compatibility fixes

Security fixes and PHP compatibility fixes (e.g., support for PHP 8.5 or 8.6) should go to the lowest branch that they can affect (2.20.x for fixes affecting 2.x, 3.7.x for fixes only affecting ORM 3).

Forward-compatibility improvements with ORM 3

Improvements to the existing forward-compatibility layer that help with the upgrade path from ORM 2 to ORM 3 can be added to 2.21.x.

Regular bugfixes

Regular bugfixes should go to 3.7.x. They will be merged up to higher branches by maintainers.

New features and refactorings

New features and refactorings should go to 3.8.x.

Deprecations

New deprecations can be added on 3.8.x. There should be a resolution of each deprecation in 4.0.x.

Breaking changes

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

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