Documentation: gitting started guide & policy

[eclairevoyant]

Problem

Currently we expect contributors to follow a git rebase flow and label commits according to a strict set of guidelines. However, there are some limitations here:

• Simpler contributions, e.g. oneliners or typo fixes, get sidelined just because they don't follow the git rebase flow or the commit guidelines
• Newer-to-github contributors, who may have a useful fix, struggle to handle rebases. Common points of struggle:
  • Merging master into the PR
  • PRs against the wrong branch
  • Accepting requested changes in the Github web UI, but then not being able to squash the commits
  • Duplicating commits
  • Closing the PR because an empty push happened (some GH-related quirk)
  • Mass pings due to incorrectly rebasing

Ordinarily, I would suggest simply having a committer fix up the branch before merging, but this has its own caveats:

• If the source branch is in a fork under a GH org (not a user), committers cannot push to the branch
• The guidelines also discourage this sort of fixup:

  Pull requests should not be squash merged in order to keep complete commit messages and GPG signatures intact and must not be when the change doesn't make sense as a single commit.

Though I don't see committers consistently paying attention to this guideline anyway, it feels more like a suggestion. The policy may be worth reconsidering.

Overall, this whole process does in fact drive away contributors; many contributors either open a new PR if they mess things up (which IMO is even more disruptive as you lose the continuity of discussion), or they give up entirely. I even saw one contributor open 3 separate PRs in a row, have rebase issues on all of them, then disappear afterwards.

Besides, nitting about something that can't be easily explained in a GH comment doesn't feel good, and takes more time and effort (and stress for the new contributor) than fixing it ourselves. But I feel we didn't set the contributors up to succeed in the first place if we just link to another massive document for them to read through (some of which even conflicts with our guidelines).

PS. I never understood the reason for enforcing a commit format, what was the reason for this? Are we using some automation that depends on it? Same goes for merge commits, what is the negative impact of having those in the PR? When we merge the PR we generate such merge commits in the history anyway.

Proposal

PR-ing against the correct branch must continue to be enforced, for CI and hydra-related reasons, but we should either:

• have some latitude to relax some of the remaining guidelines (particularly around the rebase workflow) for new contributors, or
• consistently take the opportunity to correct the PRs as committers instead of overly nitting and/or blocking merges about it, or
• have an airtight guide that covers all common use cases and some other rarer ones as well - be exactly specific on how to clone, how to rebase, etc. and then categorically reject (via CI, ideally) any PR that doesn't follow these guidelines.

Checklist

• [x] checked latest Nixpkgs manual (source) and latest NixOS manual (source)
• [x] checked open documentation issues for possible duplicates
• [x] checked open documentation pull requests for possible solutions

A previous issue #300113 + associated PR exists on this topic, but they're marked completed, and I don't find a more overarching issue about this.

---

Add a :+1: reaction to issues you find important.

[AndersonTorres]

It looks like a problem that arises because the GitHub webapp is a clearly subpar experience.

And this is not because the commandline interface is somewhat superior. I use Magit from Emacs most of the time.

[eclairevoyant]

Yeah, it doesn't help that GH tries to impose the merge workflow rather than rebase.