Update the documentation for how staging-next works

[alyssais]

The documentation for the staging-next branch currently says

19.7.3. Staging-next branch

The staging-next branch is for stabilizing mass-rebuilds submitted to the staging branch prior to merging them into master. Mass-rebuilds must go via the staging branch. It must only see non-breaking commits that are fixing issues blocking it from being merged into the master branch.

If the branch is already in a broken state, please refrain from adding extra new breakages. Stabilize it for a few days and then merge into master.

The "must only see non-breaking commits that are fixing issues blocking it from being merged into the master branch" is not at all how staging-next actually works today. Mesa updates always go to staging-next, and so do small updates that depend on other things in staging-next that haven't reached master yet, e.g. #137430.

I don't mind if this is the way staging-next works now, but I do mind that the documentation doesn't reflect this use, because it means that people who have read and are trying to follow the rules in the manual are using a different, more restrictive set of rules from everybody else.

[jtojnar]

Maybe something like: “It must only see commits that do not interfere with the stabilization, primarily non-breaking commits that are fixing issues blocking it from being merged into the master branch. But low risk changes like leaf packages that depend on a feature being stabilized are also acceptable.”

The concern is that it might empower people to push more stuff to staging-next and breaking stabilization (e.g. “surely, this wonʼt break anything”)

I have no idea about the reasoning for why mesa goes there.

[stale]

I marked this as stale due to inactivity. → More info

[FRidh]

Related #83381

[samueldr]

The documentation has moved here:

• https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md#staging

The wording changed, too. I presume usage might have too, since.

I'm tentatively closing this issue, @alyssais feel free to re-open if this is wrong.