Description
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
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