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