marc/packwatch
Archived
1
0
Fork 0
Code Issues 5 Pull requests 10 Projects Releases 2 Packages Wiki Activity

Better documentation #19

Merged
mcataford merged 6 commits from best-practices-docs into master 2020-05-02 02:08:06 +00:00
Conversation 1 Commits 6 Files changed 2 +5 -3
1 changed files with 5 additions and 3 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit c8c2d20d59 - Show all commits

8
BEST_PRACTICES.md
View file

@ -4,6 +4,8 @@
Monitoring the footprint of the packages you publish can be a powerful first step towards being producing efficient, trim code that doesn't use more resources that it should and that is a no-brainer to adopt. This document compiles some suggestions on how to get the most out of packwatch for your project. Monitoring the footprint of the packages you publish can be a powerful first step towards being producing efficient, trim code that doesn't use more resources that it should and that is a no-brainer to adopt. This document compiles some suggestions on how to get the most out of packwatch for your project.
Got best practices questions or suggestions? Open an [issue](https://github.com/mcataford/packwatch/issues)!
### Understanding `.packwatch.json` ### Understanding `.packwatch.json`
The `.packwatch.json` file persisted in your project keeps track of the last reported package size that was commited to your version control system. At the moment, it consists of three keys: The `.packwatch.json` file persisted in your project keeps track of the last reported package size that was commited to your version control system. At the moment, it consists of three keys:
@ -16,10 +18,10 @@ While the `packageSize` and `unpackedSize` are automatically populated when you
#### Setting sensible thresholds #### Setting sensible thresholds
When Packwatch initializes its manifest, it will initialize the `limit` parameter to be equal to `packedSize` so that any increase in size will cause a failure. Once you determine what kind of growth you want to allow for, you can edit the manifest to increase the limit. Any automatic updates to the manifest will leave the `limit` value as-is. When Packwatch initializes its manifest, it will initialize the `limit` parameter to be equal to `packedSize` so that any increase in size will cause a failure. Once you determine what kind of growth you want to allow for, you can edit the manifest to increase the limit.__ Any automatic updates to the manifest will leave the `limit` value as-is__.
Setting a sensible limit is essential to avoiding "packwatch fatigue", a scenario in which packwatch fails every time your package size grows because the `limit` parameter is too close to the `packageSize` value. Usually, having a limit that is more or less 5 kB above the `packageSize` will allow for growth while still preventing bloat to sneak it. From there, you can readjust the `limit` value as your project grows so that the "head room" space between `packageSize` and `limit` stays adequate. Setting a sensible limit is essential to avoiding "packwatch fatigue", a scenario in which packwatch fails every time your package size grows because the `limit` parameter is too close to the `packageSize` value. Usually, __having a limit that is more or less 5 kB above the `packageSize` will allow for growth while still preventing bloat to sneak in__. From there, you can readjust the `limit` value as your project grows so that the "head room" space between `packageSize` and `limit` stays adequate.
### Integrating Packwatch into your workflow ### Integrating Packwatch into your workflow
In order to monitor your project's growth accurately, it's preferrable to have Packwatch run both in your pre-commit hooks and CI pipeline. This way, you can catch bloat before commits are event pushed up and you can get another chance to catch undesired overgrowth before you merge in change bundles. In order to monitor your project's growth accurately, it's preferrable to have Packwatch run both in your pre-commit hooks and CI pipeline. This way, you can catch bloat before commits are event pushed up and you can get another chance to catch undesired overgrowth before you merge in change bundles. This will also act as a reminder to keep the manifest up to date so that it doesn't go out sync.