mirror of
https://github.com/Llewellynvdm/nativefier.git
synced 2024-06-06 06:20:47 +00:00
HACKING.md: embed video showing what a live-reload experience looks like
Also, a paragraph on limiting breaking changes
This commit is contained in:
parent
62ee24662c
commit
1ceffb1a0d
21
HACKING.md
21
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,
|
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.
|
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.
|
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 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,
|
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
|
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 :) .
|
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
|
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.
|
more tailored to our use case, and less complexity is good.
|
||||||
4. Use **types**, avoid `any`, write **tests**.
|
5. Use **types**, avoid `any`, write **tests**.
|
||||||
5. **Document for users** in `API.md`
|
6. **Document for users** in `API.md`
|
||||||
6. **Document for other devs** in comments, jsdoc, commits, PRs.
|
7. **Document for other devs** in comments, jsdoc, commits, PRs.
|
||||||
Say _why_ more than _what_, the _what_ is your code!
|
Say _why_ more than _what_, the _what_ is your code!
|
||||||
|
|
||||||
## Setup
|
## 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:
|
- For a good live experience, open two terminal panes/tabs running code/tests watchers:
|
||||||
1. Run a TSC watcher: `npm run build:watch`
|
1. Run a TSC watcher: `npm run build:watch`
|
||||||
2. Run a Jest unit tests watcher: `npm run test: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`
|
- Alternatively, you can run both test processes in the same terminal by running: `npm run watch`
|
||||||
|
|
||||||
## Release
|
## Release
|
||||||
|
|
Loading…
Reference in New Issue
Block a user