From 88835e63bd0c37b7be99f63214d17a429d937035 Mon Sep 17 00:00:00 2001 From: Paulo Castro Date: Thu, 7 Apr 2022 16:38:23 +0100 Subject: [PATCH] Document the 'patches' folder in CONTRIBUTING.md Change-type: patch --- CONTRIBUTING.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 916067b0..1e2d8971 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -125,6 +125,39 @@ The README file is manually edited, but subsections are automatically extracted The `INSTALL*.md` and `TROUBLESHOOTING.md` files are also manually edited. +## Patches folder + +The `patches` folder contains patch files created with the +[patch-package](https://www.npmjs.com/package/patch-package) tool. Small code changes to +third-party modules can be made by directly editing Javascript files under the `node_modules` +folder and then running `patch-package` to create the patch files. The patch files are then +applied immediately after `npm install`, through the `postinstall` script defined in +`package.json`. + +The subfolders of the `patches` folder are documented in the +[apply-patches.js](https://github.com/balena-io/balena-cli/blob/master/patches/apply-patches.js) +script. + +To make changes to the patch files under the `patches` folder, **do not edit them directly,** +not even for a "single character change" because the hash values in the patch files also need +to be recomputed by `patch-packages`. Instead, edit the relevant files under `node_modules` +directly, and then run `patch-packages` with the `--patch-dir` option to specify the subfolder +where the patch should be saved. For example, edit `node_modules/exit-hook/index.js` and then +run: + +```sh +$ npx patch-package --patch-dir patches/all exit-hook +``` + +That said, these kinds of patches should be avoided in favour of creating pull requests +upstream. Patch files create additional maintenance work over time as the patches need to be +updated when the dependencies are updated, and they prevent the compounding community benefit +that sharing fixes upstream have on open source projects like the balena CLI. The typical +scenario where these patches are used is when the upstream maintainers are unresponsive or +unwilling to merge the required fixes, the fixes are very small and specific to the balena CLI, +and creating a fork of the upstream repo is likely to be more long-term effort than maintaining +the patches. + ## Windows Besides the regular npm installation dependencies, the `npm run build:installer` script