Add an errata section?

[joachifm]

Sometimes we need to break the stable contract as with deprecating grsecurity or when a bug fix requires bumping packages beyond what is normally done (due to lack of manpower to backport just the fixes). An entry in the changelog might not be too easy for users to discover, however, nor may they think to check the changelog for such things.

What about adding an "errata" with dated entries (or some other method of clearly letting the user know that they are affected), listing instances where changes have been made to a stable branch that requires user intervention of some sort or otherwise breaks the stable contract. We could then recommend checking the errata before nixos-rebuild &c.

Alternatively, we should at least establish a protocol for adding the appropriate information to an existing section in the manual (I'm pretty sure we break the stable contract quite often in pursuit of fixing security bugs, for example, without ever documenting it in a user-visible manner).

[joachifm]

To clarify, I've done this myself so I'm certainly not calling anybody out for breaking the stable contract! Just looking for ways to approach it systematically.

[joachifm]

An errata entry would comprise at least the what, why, when, and user intervention if any, with links to commits &c.

[0xABAB]

This falls in the category "our project has a too large scope, so let's fight the symptoms". The problem with the NixOS project is that while some core features related to the Linux kernel improve, the bulk of the work is in package maintenance, bumping versions, etc. That bulk of the work requires way too much attention that could be automated (and would be automated if NixOS was Google).

Similarly, way too much time is spent on arguing about commits, while it's obvious that the project would be better off with those commits than without.

If the project was organised better, there would be no need to argue about commits.

Related to scope management, we seem to package inferior products too. Sometimes, some solutions are simply better. Instead of allowing those inferior solutions to exist and take up resources, we should simply say that not everything is good enough to be packaged. I am sure you can come up with your own personal favorites regarding this.

[joachifm]

@0xABAB errata are for changes already committed to master. The purpose is not to determine what to integrate, but to document changes that must be backported to release despite violating the stable contract. If done consistently, this helps increase confidence that nixos-rebuild against a stable release channel won't have unexpected side-effects.

[FRidh]

Unfortunately it happens that we sometimes have to make some larger changes in stable, and I agree we need a way to inform users what larger changes were made.

For each stable release we have a changelog. How about adding an errata section there?

[joachifm]

@FRidh sounds good to me.

For contributors we could add a note in the commit guidelines (?) to take a moment to consider whether an errata is warranted when backporting stuff (usually the answer should be "no", ofc). For users it'd be good to mention checking the errata as a good practice.

[FRidh]

@joachifm I suggest you send an e-mail to nix-dev about this issue.

[joachifm]

cc @globin @fpletz

[stale[bot]]

Thank you for your contributions.

This has been automatically marked as stale because it has had no activity for 180 days.

If this is still important to you, we ask that you leave a comment below. Your comment can be as simple as "still important to me". This lets people see that at least one person still cares about this. Someone will have to do this at most twice a year if there is no other activity.

Here are suggestions that might help resolve this more quickly:

1. Search for maintainers and people that previously touched the related code and @ mention them in a comment.
2. Ask on the NixOS Discourse.
3. Ask on the #nixos channel on irc.freenode.net.

[joachifm]

still important to me

[stale[bot]]

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