doc: Add a note about backporting #17159

(e.g., a security issue) or on request.

Thank you. A nice one. I actually learned something. https://www.dailywritingtips.com/comma-after-i-e-and-e-g/

just request a "Needs backport" label for the original PR.

Done in 7c5ce792ef498598bd57780d42938139dbcd58e7 and will be squashed in the end.

Could mention that the PR must be for a specific branch, not master. Also, a PR may be needed for each version where the backport makes sense.

nit, drop "wait for comments"?

Why a specific branch, not master? I understand that my development is done on a specific branch in my forked repo, but I ask for the Pull Request to master.

"wait for comments" dropped in 1d9ffdd2432f9a89f77204505b221616cf74b704 and will be squashed in the end

Backports are done when something is already in master (that is the practice of Linux development, where git itself comes from; in contrary to what Android or other BSP developers tend to do - they add specific hardware patches to a stable branch, making master run away quickly and then they are unable to catch up so after the device is not sold anymore, one can hardly find a current kernel and Android build for it...)

Why a specific branch, not master? I understand that my development is done on a specific branch in my forked repo, but I ask for the Pull Request to master.

Commits are backported from the master branch to a specific branch, e.g., 0.18 or 0.19; not to the master branch.

@promag @hebasto OK, sorry. I totally misunderstood the comment.

@promag What do you think about 2aa9503ea ?

Each commit message of a backport ...

Thanks. Fixed in 163fe28c54105fdde687cc49c51e635d6e483ccb and will be squashed later into the final commit.

commit hash of the respective merged commit?

Fixed in 842aa85aa ...

This should only ever be a PR number.

Github-Pull: #<PR number>

Rebased-From: <commit hash of the original commit>

Done. 57379c8a5

Aah, I just realized this "Commit suggestion" button :-) Will try it next time.

Also see the [backport.py script](

This is intended to be a new policy?

As far as I understood, we are just describing the commonly used, but yet uncodified process. Or is it something new @laanwj ?

This is intended to be a new policy?

It's not a new policy, just what happens in reality (when looking at bulk backports). However if this is controversial just drop the sentence.

Maybe mention that the Needs backport (...) labels are a tracking tool for maintainers and not meant as a TODO for the author of the PR. This has confused a few people.

@laanwj see 4d47775c1

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d38e44c47..f36f29dcf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -317,7 +317,9 @@ branches.
 If the backport is non-trivial, it may be appropriate to open an
 additional PR, to backport the change, only after the original PR
 has been merged.
-Otherwise, backports will be done in batches by maintainers.
+Otherwise, backports will be done in batches by maintainers and
+the maintainers will use the proper `Needs backport (...)` labels
+when needed (the original author does not need to worry).

 A backport should contain the following metadata in the commit body:

... unless a straightforward merge of the original branch is possible.

Why would a straightforward merge of something which has different checksum in master branch not contain a pointer to the parent (original commit in master)?

Please provide some git command line examples on how to find the equivalent commit in master, given a release commit. If possible and if I understand correctly. Thank you.

Sometimes it's possible to base a new commit on a commit before the branch split (e.g. between 0.19 and master). If nothing conflicts in between, it can be a clean merge to both branches (unclean merges are rejected by the CI checks). This is quite rare, though, and I'm not sure mentioning it here is important. If you're enough of a git guru to do this, you don't need it mentioned here.

@laanwj I see. @luke-jr Was this ^^ what you meant?

I still think that one commit has to be the first one (in linear time) and merged into master. Then any other cherry-pick, no matter if there were conflicts, should IMHO contain a reference to the original unless it is easy in git to find out the original (first) patch on which this "backport" is based...

Yes, no matter how they're represented in git, changes should still be merged first into master. This is to make absolutely sure that the future major release contains everything.

Right. My point was just if there is a better way to find "parent" (i.e. original upstream patch) but I found there is not because even in Linux kernel development (and I suppose they know how to use git given it was born there) they always write a comment in a backported patch:

commit <hash> upstream.

See this backported patch which is backport of this original patch in master and the only difference between those two is the added comment:

--- patchorig   2019-10-30 14:00:51.058777980 +0100
+++ backport    2019-10-30 14:00:30.865990235 +0100
@@ -1,9 +1,11 @@
-commit 3dd550a2d365
+commit 9f8dd40c68c1
 Author: Alan Stern <stern@rowland.harvard.edu>
 Date:   Wed Sep 4 11:56:27 2019 -0400

     USB: usbcore: Fix slab-out-of-bounds bug during device reset

+    commit 3dd550a2d36596a1b0ee7955da3b611c031d3873 upstream.
+
     The syzbot fuzzer provoked a slab-out-of-bounds error in the USB core:

     BUG: KASAN: slab-out-of-bounds in memcmp+0xa6/0xb0 lib/string.c:904

So maybe I totally misunderstood @luke-jr and was solving some non-issue here, but I learned a lot. Thanks!

Yes, bugfixes are best when based immediately on top of the commit introducing the bug, in which case it is a clean merge to all affected branches.

Sometimes that's not possible and a cherry-pick is needed instead, but when it is possible, it should be preferred.

(Linux doesn't set a good example in this regard.)

Maybe just remove "maintainers" here?

https://github.com/carnhofdaki/bitcoin/commit/9e35eaeddbb46405e30c05de27ebdb7aa4e87fd1