octoleo
/
nativefier
mirror of https://github.com/Llewellynvdm/nativefier.git
2
2
Fork 0
Code Issues Releases Activity

HACKING.md: embed video showing what a live-reload experience looks like 

Also, a paragraph on limiting breaking changes
This commit is contained in:
Ronan Jouchet 2021-06-02 09:48:57 -04:00
parent 62ee24662c
commit 1ceffb1a0d
1 changed files with 17 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
HACKING.md
View File

@ -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