nixos/rfcs
1
0
Fork 0
mirror of https://github.com/NixOS/rfcs.git synced 2025-11-08 19:46:12 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

[RFC 0088] Nixpkgs Breaking Change Policy (#88)

Browse source 
* Create RFC for nixpkgs Breaking Change Policy

This specifies the expected workflow as a base for workflows and future automation.

* Update rfcs/0088-nixpkgs-breaking-change-policy.md

Co-authored-by: asymmetric <lorenzo@mailbox.org>

* Reformat metadata

* Update and clarify.

- Highlight the high-level goal.
- Highlight the low-level goal of this specific RFC.
- Wording fixes.

* Implement suggestions from shepherds meeting.

* Set shepherd leader

Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>

* Typo fix

Co-authored-by: Théo Zimmermann <theo.zimmi@gmail.com>

Co-authored-by: asymmetric <lorenzo@mailbox.org>
Co-authored-by: Linus Heckemann <git@sphalerite.org>
Co-authored-by: Eelco Dolstra <edolstra@gmail.com>
Co-authored-by: Jörg Thalheim <Mic92@users.noreply.github.com>
Co-authored-by: Théo Zimmermann <theo.zimmi@gmail.com>
This commit is contained in:
Kevin Cox 2021-11-17 09:15:33 -05:00 • committed by GitHub
parent fe4b5325ac
commit a36c8e90c3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 156 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

156
rfcs/0088-nixpkgs-breaking-change-policy.md Normal file
View file

@ -0,0 +1,156 @@
---
feature: nixpkgs-breaking-change-policy
start-date: 2020-09-24
author: Kevin Cox
co-authors: (TBD)
shepherd-team: @blaggacao, @jonringer, @nrdxp
shepherd-leader: @blaggacao
related-issues: (TBD)
---
# Summary
This defines a policy for how to manage nixpkgs changes that break dependent
derivations or tests. It specifies timeframes and procedures so that
maintainers of dependencies and dependents can know what to expect from each
other when making breaking changes.
While this policy should be followed as much as possible once accepted it is
primarily focused on getting agreement such that tools can be built that make
implementing this policy very easy. See the [Future Work section](#future-work)
for examples of the tools that will be built.
The direct intended result of this RFC is:
- Maintainers of dependencies have a clear framework for handling changes that
break dependants.
- Maintainers of dependants have a clear framework for how dependency breacking
changes will be handled.
- NixOS channels will very rarely (ideally never) stall due to build or test
failures.
This document is only focused on changes to derivation builds and tests it
**does not** aim to make any opinion on changes that can break user machines or
configurations. (While this is an interesting topic it is harder to put
concrete rules on due to the difficulty of identifying these breakages. In
order to be covered by this policy please put tests on your packages.)
# Motivation
Right now the procedure for making breaking changes varies widely by maintainer
and is largely tribal knowledge. There are a wide variety of approaches ranging
from:
- After testing to confirm that a change is correct, merge and notify
dependents that they need to update their packages.
- Merge to `staging`, notify dependents then eventually merge to `master`.
- Gather a large number of fixes in the PR branch then merge to `staging` or
`master` once most or all dependencies are fixed.
This adhoc nature has a number of downsides:
- Change authors need to put effort into deciding how to handle each particular
change.
- Maintainers of dependant packages don't know what to expect and have a hard
time keeping up with upstream breakages.
- Merges to `master` or `staging` can result in broken channels which block all
updates including security updates.
This aims to provide a uniform approach so that everyone involved knows what to
expect and to allow further workflows including automation to be build on top
of these procedures.
## Past Discussions
https://discourse.nixos.org/t/please-fix-all-packages-which-were-broken-by-the-qt-wrapping-changes/6444
# Detailed design
## Goals
The following procedure will be used for making breaking changes. It has a few
primary goals:
- Avoid putting more burden than necessary on the dependency maintainer. If the
maintainers of core derivations face toil proportionally to the number of
transitive dependencies they will quickly become overloaded. These
maintainers are arguably the most critical to Nixpkgs and their load needs
to be kept manageable.
- Avoid unnecessarily breaking packages for any period of time. There are a
number of users on the `*-unstable` channels and it is annoying if packages
in their configuration get broken.
- Avoid breaking the `master` branch as much as possible. The `master` branch
is used by the `*-unstable` channels and breaking this branch means that no
updates can be pushed. This includes critical security updates as well as
regular feature updates.
## Procedure
The target branch for a merge is not affected by this policy. It will be
picked, as it is today, according to
https://nixos.org/manual/nixpkgs/stable/#submitting-changes-commit-policy.
1. The maintainer will prepare a PR with their intended changes.
2. The maintainer should test a sample of dependent derivations to ensure that
their change is not unnecessarily or unintentionally breaking. (Example: Ensure
that a critical output file was not forgotten) Note that sometimes it **is**
necessary to break all dependent packages, and the maintainer is not required
to avoid this.
1. A sample of at least 100 packages or 3h of build time is recommend as a guideline.
2. The sample should include as many `passthru.tests` tests as is feasible.
3. The maintainer will get the PR reviewed and approved.
1. It is **recommended but not required** to have some maintainers of
dependent packages involved in the review to review if the breakage is
justified.
4. The maintainer will contact the maintainers of all dependent, broken
packages (herein called sub-maintainers).
1. The sub-maintainers will be provided a link to the PR with the breaking
changes as well as any context that will help them resolve the breakages.
2. The sub-maintainers are expected to update the derivations that they
maintain within 7 days.
1. These changes should be merged to the target branch following the regular
nixpkgs PR process if they are backwards compatible. Otherwise they
will be merged into the branch of the breaking PR.
5. The maintainer must provide a grace period of at least 7 days from when the
sub-maintainers were notified.
6. The maintainer must merge the target branch into their PR branch.
7. The maintainer must mark all still-broken packages as
[broken](https://nixos.org/manual/nixpkgs/stable/#sec-standard-meta-attributes).
8. The maintainer can now merge to the target branch.
This procedure should not result in a failing channel build in the target
branch at any point. In particular NixOS channel constituents are considered
blocking and are an exception to the 7 day breakage rule.
# Drawbacks
This delays the merge of "core" derivations as the author needs to wait for
sub-packages to be tested and possibly fixed up to the 7 day threshold.
# Alternatives
## Shorter grace period
A shorter grace period allows maintainers to move more quickly but requires
maintainers of defendant derivations to jump to action quickly which is not
always possible for volunteer driven work. For example if a maintainer is on
vacation they can't be expected to respond in a couple of days.
## Longer grace period
A longer grace period would give derivation maintainers more time to react to
changes in dependencies and provide more time to search for replacement
maintainers if the original maintainer has abandoned the derivation. The 7 day
number was mostly arbitrary and can easily be changed in the future. A longer
grace period would also result in more packages being fixed before the breaking
change is shipped, which results in less breakage for end-users.
# Unresolved questions
None.
# Future work
- Create a tool for automatically notifying maintainers of broken dependents
- Create a tool for automatically marking broken packages as broken.
- [This is a milestone on the way to implemented a queue-based merge process
for nixpkgs.](https://paper.dropbox.com/doc/MTSY8xKH6y1xDEwavyDNW)