From beae6e872bd94a27edb948483bd0a8c56622577b Mon Sep 17 00:00:00 2001 From: Ronan Jouchet Date: Sun, 2 May 2021 18:29:05 -0400 Subject: [PATCH] development.md: expand on why I'm such a bore with limiting extra deps --- docs/development.md | 26 +++++++++++++++++--------- 1 file changed, 17 insertions(+), 9 deletions(-) diff --git a/docs/development.md b/docs/development.md index 0f8e84a..9ad45fc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -5,20 +5,28 @@ need to know to get started hacking on Nativefier. ## Guidelines -1. Before starting work on a huge change, gauge the interest +1. **Before starting work on a huge change, gauge the interest** of community & maintainers through a GitHub issue. - For big changes, create a [RFC](https://en.wikipedia.org/wiki/Request_for_Comments) + For big changes, create a **[RFC](https://en.wikipedia.org/wiki/Request_for_Comments)** issue to enable a good peer review. -2. Do your best to avoid adding new Nativefier command-line options. +2. Do your best to **avoid adding new Nativefier command-line options**. 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 or limit adding npm dependencies. - Each new dependency is a complexity & security liability. -4. Use types, avoid `any`, write tests. In that order. -5. Document for users in API.md -6. Document for other devs in comments, jsdoc, commits, PRs. - Say *why* more than *what*, the *what* is your code! +3. **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 + "just a little extra dep". Without this constant attention, Nativefier would be + more bloated, less stable for users, more annoying to maintainers. Now, don't go + rewriting zlib if you need a zlib dep, for sure use a dep. But if you can write a + 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. + Say _why_ more than _what_, the _what_ is your code! ## Setup