From a254402a466ab44fd5e9fb98f506f90cd3a51843 Mon Sep 17 00:00:00 2001
From: Paul Meyer <49727155+katexochen@users.noreply.github.com>
Date: Thu, 18 Jul 2024 11:16:43 +0200
Subject: [PATCH] dev-docs: document patching conventions

Signed-off-by: Paul Meyer <49727155+katexochen@users.noreply.github.com>
---
 dev-docs/patches.md                           | 109 ++++++++++++++++++
 .../config/vocabularies/edgeless/accept.txt   |   4 +
 2 files changed, 113 insertions(+)
 create mode 100644 dev-docs/patches.md

diff --git a/dev-docs/patches.md b/dev-docs/patches.md
new file mode 100644
index 0000000000..d241846528
--- /dev/null
+++ b/dev-docs/patches.md
@@ -0,0 +1,109 @@
+# Working with patches
+
+## Patches in Nix
+
+There are two common ways to apply patches in Nix:
+
+- Use the `patches` attribute of a builder ([manual](https://nixos.org/manual/nixpkgs/unstable/#var-stdenv-patches)):
+
+  ```nix
+  stdenv.mkDerivation {
+    # ...
+    patches = [
+        ./0001-first-change.patch
+        ./0002-another-change.patch
+    ]
+    # ...
+  }
+  ```
+  This is most commonly used and can be encountered nearly everywhere upstream in nixpkgs.
+
+- Use the `applyPatches` function ([noogle](https://noogle.dev/f/pkgs/applyPatches)) to patch an existing source and derive a new source:
+
+  ```nix
+  stdenv.mkDerivation {
+    # ...
+    src = applyPatches {
+        src = fetchFromGuiHub { /* ... */ }
+    patches = [
+        ./0001-first-change.patch
+        ./0002-another-change.patch
+    ]
+    # ...
+  }
+  ```
+
+  This is useful in situations where the patches sources should also be used by other consumers, as the
+  patched source can inherited, but `patches` aren't part of the output set.
+
+Patches can either be consumed from a local file or pulled from remote:
+
+```nix
+patches = [
+  (fetchpatch {
+    url = "https://github.com/...";
+    stripLen = 2; # Sometimes the patch strip level must be configured
+    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+  })
+];
+```
+
+If there aren't any changes needed to an upstream patch, it's good practice to fetch the patch from remote.
+The patch should come from a stable ref in this case, like from a persistent upstream branch or an open pull request.
+If the changes to upstream patches are needed or patches aren't available upstream, the
+*full patch set* should be vendored (don't mix `fetchpatch` and local patches on the same target), so it can easily be worked with.
+
+## Patch set development flow
+
+For a smooth development experience, we only use `git format-patch` format for patches. This enables us
+to apply the changes to the source, work on it and sync back.
+
+Given a package with some existing patches in `pkgDir` (for example `packages/by-name/contrast`).
+
+Clone the source and checkout the `rev` currently used in the package `src` (the commit or tag):
+
+```sh
+git clone $url
+git checkout $rev
+```
+
+Apply the existing patch set:
+
+```sh
+git am -3 $pkgDir/*.patch
+```
+
+This will apply and commit each patch on top of `rev`.
+
+You can then place new commits on top or modify existing commits. Remember to keep the git history clean.
+
+When updating a package, you might need to rebase the current patch set.
+
+When done, recreate the patch set:
+
+```sh
+git format-patch -o $pkgDir $rev
+```
+
+# Patch documentation conventions
+
+Patches need thorough documentation. Each reference of a patch must have a comment:
+
+```nix
+patches = [
+  # Document things about the patch here
+  ./0001-first-change.patch
+]
+```
+
+Notice that this is in addition to writing a sensible commit message in case you create
+a commit specifically for a patch. In many cases, commit message of a patch will come from
+original patch author, so all the meta goes where the patch is referenced.
+
+The comment should answer the following questions:
+
+- Why is the patch needed?
+- Is the patch already merged? -> Make a note that the patch can be removed on next update.
+- Is the patch part of an open upstream PR? -> Link to the upstream PR.
+- If it's an upstream patch, was the patch modified? If yes, what was changed and why?
+- If the patch has no upstream PR, why can't we upstream the change?
diff --git a/tools/vale/styles/config/vocabularies/edgeless/accept.txt b/tools/vale/styles/config/vocabularies/edgeless/accept.txt
index b3bee96436..e7bfba2e86 100644
--- a/tools/vale/styles/config/vocabularies/edgeless/accept.txt
+++ b/tools/vale/styles/config/vocabularies/edgeless/accept.txt
@@ -120,3 +120,7 @@ WireGuard
 Xeon
 xsltproc
 Zipkin
+vendored
+noogle
+nixpkgs
+rebase