From 3e5907a087e79aa3fdc7084e0061b5f241b85784 Mon Sep 17 00:00:00 2001 From: Ronan Jouchet Date: Mon, 28 Jun 2021 23:30:17 -0400 Subject: [PATCH] HACKING.md: document a few maintainer deps things --- HACKING.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/HACKING.md b/HACKING.md index 61a5102..c681613 100644 --- a/HACKING.md +++ b/HACKING.md @@ -117,7 +117,7 @@ but is painful to do manually. Do yourself a favor and install a ## Maintainers corner -### Major-updating Electron +### Deps: major-updating Electron When a new major [Electron release](https://github.com/electron/electron/releases) occurs, @@ -134,6 +134,46 @@ When a new major [Electron release](https://github.com/electron/electron/release 1. If `master` has unreleased commits, make a patch/minor release with them, but without the major Electron bump. 2. Commit your Electron major bump and release it as a major new Nativefier version. Help users identify the breaking change by using a bold **[BREAKING]** marker in `CHANGELOG.md` and in the GitHub release. +### Deps updates + +It is important to stay afloat of dependencies upgrades. +In packages ecosystems like npm, there's only one way: forward. +The best time to do package upgrades is now / progressively, because: + +1. Slacking on doing these upgrades means you stay behind, and it becomes + risky to do them. Upgrading a woefully out-of-date dep from 3.x to 9.x is + scarier than 3.x to 4.x, release, then 4.x to 5.x, release, etc... to 9.x. + +2. Also, dependencies applying security patches to old major versions are rare + in npm. So, by slacking on upgrades, it becomes more and more probable that + we get impacted by a vulnerability. And when this happens, it then becomes + urgent & stressful to A. fix the vulnerability, B. do the required major upgrades. + +So: do upgrade CLI & App deps regularly! Our release script will remind you about it. + +### Deps lockfile + +Although there are benefits to a package lock (reproducible builds, install speed), +as of writing, Nativefier doesn't use one. We tried it, and removed it after seeing +it confused novice devs sending PRs. They don't know how to manage it, they update +the package.json but not the lock, it's a hassle, they get discouraged. + +At time of writing, maximizing simplicity and ease of contribution +seems preferable over reproducible builds and install speed. + +Also, practically, the npm ecosystem today is stable enough that non-reproducible +builds never caused any trouble in years (zero issues/complaints related to it). +Semantic versioning is well respected, our users get patch/minor upgrades, +a build at time T1 works, and a different build at time T2 > T1 works too 🙂. + +Finally, it's not a problem for distributions / user repositories wishing to +provide reproducible builds, because if a repo (say, AUR) wants to make *their* +build reproducible, they can: the packager can add a lockfile to their PKGBUILD +associated files, and it will be reproducible for them. + +This is of course debatable and may change in the future based on bugs, +user feedback, or future maintainers preference. + ### Release While on `master`, with no uncommitted changes, run: