From 1ceffb1a0d8e3719654ac234cdfe80b023598562 Mon Sep 17 00:00:00 2001 From: Ronan Jouchet Date: Wed, 2 Jun 2021 09:48:57 -0400 Subject: [PATCH] HACKING.md: embed video showing what a live-reload experience looks like Also, a paragraph on limiting breaking changes --- HACKING.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/HACKING.md b/HACKING.md index 9ad45fc..37b6a76 100644 --- a/HACKING.md +++ b/HACKING.md @@ -13,7 +13,18 @@ need to know to get started hacking on Nativefier. If a new option is inevitable for what you want to do, sure, but as much as possible try to see if you change works without. Nativefier already has a ton of them, making it hard to use. -3. **Avoid adding npm dependencies**. Each new dep is a complexity & security liability. +3. Do your best to **limit breaking changes**. + Only introduce breaking changes when necessary, when required by deps, or when + not breaking would be unreasonable. When you can, support the old thing forever. + For example, keep maintaining old flags; to "replace" an flag you want to replace + with a better version, you should keep honoring the old flag, and massage it + to pass parameters to the new flag, maybe using a wrapper/adapter. + Yes, our code will get a tiny bit uglier than it could have been with a hard + breaking change, but that would be to ignore our users. + Introducing breaking changes willy nilly is a comfort to us developers, but is + disrespectful to end users who must constantly bend to the flow of breaking changes + pushed by _all their software_ who think it's "just one breaking change". +4. **Avoid adding npm dependencies**. Each new dep is a complexity & security liability. You might be thinking your extra dep is _"just a little extra dep"_, and maybe you found one that is high-quality & dependency-less. Still, it's an extra dep, and over the life of Nativefier we requested changes to *dozens* of PRs to avoid @@ -23,9 +34,9 @@ need to know to get started hacking on Nativefier. little helper function saving us a dep for a mundane task, go for the helper :) . Also, an in-tree helper will always be less complex than a dep, as inherently more tailored to our use case, and less complexity is good. -4. Use **types**, avoid `any`, write **tests**. -5. **Document for users** in `API.md` -6. **Document for other devs** in comments, jsdoc, commits, PRs. +5. Use **types**, avoid `any`, write **tests**. +6. **Document for users** in `API.md` +7. **Document for other devs** in comments, jsdoc, commits, PRs. Say _why_ more than _what_, the _what_ is your code! ## Setup @@ -95,6 +106,8 @@ but is painful to do manually. Do yourself a favor and install a - For a good live experience, open two terminal panes/tabs running code/tests watchers: 1. Run a TSC watcher: `npm run build:watch` 2. Run a Jest unit tests watcher: `npm run test:watch` + 3. This should look like this: + https://user-images.githubusercontent.com/522085/120407694-abdf3f00-c31b-11eb-9ab5-a531a929adb9.mp4 - Alternatively, you can run both test processes in the same terminal by running: `npm run watch` ## Release