docs: Add development branch section #9119
Conversation
jetm
force-pushed
the
lts-over-development-branch
branch
from
2fd6b16
to
e813ae3
Compare
CONTRIBUTING.md
Outdated
| @@ -10,7 +10,7 @@ More details on all of these points may be found in the sections below. | |||
| - [Sign-off](#license-and-copyright): all commits must be signed off. | |||
| - [Tests](#tests): please ensure the PR includes adequate tests. | |||
| - [Changelog](#documentation): if needed, please provide a changelog entry. | |||
| - [Backports](#long-term-support-branches): provide a backport if needed (it's fine to wait until the main PR is accepted). | |||
| - [Backports](#long-term-support-branches): Priority is given to the LTS branch over the development branch. After the PR has been integrated into the LTS branch, please merge it into the development branch. | |||
There was a problem hiding this comment.
Err, not really.
development is where all development happens. Some PRs will be backported into the LTS branches, but not all. So all PRs must first start on development; it is not true that priority is given to LTS branches. And each PR targets only one branch (which is different to some other projects, such as OpenSSL, where a single PR is often merged to multiple applicable branches).
What is true is that we won't merge a PR to development if we want backport PRs and they are not present. Very specifically, gatekeepers (should) merge all PRs at the same time.
Now, some people will create the backports at the same time as the main PR. This means extra work if there are changes required.
The original phrase it's fine to wait until the main PR is accepted is correct. It does not say merged.
It is fine to wait until we are happy with a PR before creating backports. But it's usually best to start with a PR against development (obviously there are special cases of issues that are only in an LTS branch, but ignoring that for the sake of a generally-applicable rule) and then create backport PRs if required/requested
There was a problem hiding this comment.
@tom-cosgrove-arm Thank you for clarifying a lot more about the workflow. Your comments are very good, and I think they should be in CONTRIBUTING.md. I have submitted a new commit, adding most of your comments.
Sorry for the forced-commit. The PR is totally different from the original change, and I thought the original commit was not necessary to keep it.
gowthamsk-arm
added
needs-review
Clarify development branch workflow to help out in submitting PRs. Signed-off-by: Javier Tia <javier.tia@linaro.org>
jetm
force-pushed
the
lts-over-development-branch
branch
from
e813ae3
to
99ac255
Compare
jetm
changed the title
| development branch is where all development happens. Some PRs will be backported into the LTS branches, but not all. So all PRs must first start with development. We won't merge a PR into development if we want backport PRs and they are not present. Very specifically, gatekeepers should merge all PRs at the same time. | ||
|
|
||
| Now, some people will create the backports at the same time as the main PR. If changes are required, this means extra work. | ||
|
|
||
| It is fine to wait until we are happy with a PR before creating backports. But it's usually best to start with a PR against development (obviously there are special cases of issues that are only in an LTS branch, but ignoring that for the sake of a generally applicable rule) and then create backport PRs if required or requested. |
There was a problem hiding this comment.
This all seems like it's spending a lot of effort providing information that people don't really need. development is the default branch for Git and on GitHub, so that's what you'll get when you clone the repository and that's what you'll target when you make a pull request. Backports need a discussion, but they already have their own section.
Description
development branch is an important part of the PR workflow, and it deserves its own section to explain its use in detail.
PR checklist
Please tick as appropriate and edit the reasons (e.g.: "backport: not needed because this is a new feature")
Notes for the submitter
Please refer to the contributing guidelines, especially the
checklist for PR contributors.
Help make review efficient: