diff options
author | Silvan Mosberger <contact@infinisil.com> | 2024-06-09 22:49:23 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-06-09 22:49:23 +0200 |
commit | d03f9e2b304d83a8378721bf6638187878d1b924 (patch) | |
tree | 17c44c2861ea676bac3abb1b87cd10ad62174f39 | |
parent | b98e90213da83b7a45732388acd13b0997609c06 (diff) | |
parent | cbfd7ee39550040fab680dab48d61f8c837ac74f (diff) |
Merge pull request #317314 from raboof/contributing-patch-conventions
pkgs/README.md: patch conventions
-rw-r--r-- | pkgs/README.md | 9 |
1 files changed, 7 insertions, 2 deletions
diff --git a/pkgs/README.md b/pkgs/README.md index fd958702fb493..53f6134f0ca67 100644 --- a/pkgs/README.md +++ b/pkgs/README.md @@ -459,7 +459,10 @@ Examples going from bad to best practices: ## Patches -Patches available online should be retrieved using `fetchpatch`. +Sometimes, changes are needed to the source to allow building a derivation in nixpkgs, or to get earlier access to an upstream fix or improvement. +When using the `patches` parameter to `mkDerivation`, make sure the patch name clearly describes the reason for the patch, or add a comment. + +Patches already merged upstream or published elsewhere should be retrieved using `fetchpatch`. ```nix { @@ -473,7 +476,9 @@ Patches available online should be retrieved using `fetchpatch`. } ``` -Otherwise, you can add a `.patch` file to the `nixpkgs` repository. In the interest of keeping our maintenance burden to a minimum, only patches that are unique to `nixpkgs` should be added in this way. +Otherwise, you can add a `.patch` file to the `nixpkgs` repository. +In the interest of keeping our maintenance burden and the size of nixpkgs to a minimum, only do this for patches that are unique to `nixpkgs` or that have been proposed upstream but are not merged yet, cannot be easily fetched or have a high chance to disappear in the future due to unstable or unreliable URLs. +The latter avoids link rot when the upstream abandons, squashes or rebases their change, in which case the commit may get garbage-collected. If a patch is available online but does not cleanly apply, it can be modified in some fixed ways by using additional optional arguments for `fetchpatch`. Check [the `fetchpatch` reference](https://nixos.org/manual/nixpkgs/unstable/#fetchpatch) for details. |