CONTRIBUTING.md: Improve backport instructions

[davidak]

Came up in #85723 (comment).

[worldofpeace]

seems good

[worldofpeace]

@davidak No where does this mention that someone could be backporting multiple commits.
So maybe commit -> commit/s?

[davidak]

is that encouraged? it could be hard to remove one controversial commit from the PR later Am 22. April 2020 01:11:01 MESZ schrieb worldofpeace <notifications@github.com>:

…

@davidak No where does this mention that someone could be backporting multiple commits. So maybe `commit` -> `commit/s`? -- You are receiving this because you were mentioned. Reply to this email directly or view it on GitHub: #85727 (comment)

-- Diese Nachricht wurde von meinem Android-Gerät mit K-9 Mail gesendet.

[FRidh]

I am not sure whether we should describe how to use git. While I can understand having a full set of instructions can be helpful to newcomers that are also somewhat unfamiliar with git, people use git differently. For example, I typically work with a detached HEAD, and push to refs/heads/<somebranch> without creating a local branch first.

Not saying it's not correct, but keep it in mind when writing instructions.

[7c6f434c]

I am not sure whether we should describe how to use `git`. While I can understand having a full set of instructions can be helpful to newcomers that are also somewhat unfamiliar with `git`, people use `git` differently. For example, I typically work with a detached HEAD, and push to `refs/heads/<somebranch>` without creating a local branch first.

I guess there are at least two audiences. One is about people who either never looked into details of how to use git, or did look but did not like what they can see there. If you want us to produce any kind of consistency with git, give us a specific recommended workflow. Otherwise it might turn out we never care about some small thing and this thing is annoying to someone. There are of course people who do have a preference about git workflows, but such people are much more likely to know whether a workflow produces indistinguishable PRs. Do you mean that the current description is too strongly worded and thus might be uncomfortable to some people in the second group, or do you mean that there are contributors not matching either of descriptions?

[FRidh]

What you write depends on which assumptions you make about the reader.

If we take your first group, and elaborate the instructions further (copy-paste quality), then one is going to have to consider more details such as the remote. How did they clone the repo? From a Nixpkgs GitHub fork or not? By not writing about how to branch/push we can avoid having to go there.

[7c6f434c]

How did they clone the repo? From a Nixpkgs GitHub fork or not?

Looking at the entire instruction and the manual — at least in a way that pushes go to the fork.

I agree we are not aiming at copy-paste quality here (at least not yet), and maybe a more realistic goal is to aim at unambiguity where enough is said to be sure one is doing what is expected (or to be unsure what exactly to do and go ask…)

[davidak]

people use git differently.

a more realistic goal is to aim at unambiguity

yes, that was my goal. currently the instructions in the README and Manual produce different results

and even tho i work every day with git, i use cherry-pick just for backporting in nixpkgs which i don't do that often. so i just followed the instructions and committed to my local release-20.03. the branch is wasted now :( the proposed change would help here. we don't really need the git push command there, that's basic git

is it encouraged to backport multiple commits in a PR? for example 20 package updates? or 6 changes to NixOS modules that fix problems? or only with small fixes?

[davidak]

I updated the commit policy to reflect the current practice in #86026 and updated the backport instructions accordingly.