From c63d573e418057615c3bd25154361cf5950827da Mon Sep 17 00:00:00 2001 From: Marc Cataford Date: Fri, 1 May 2020 21:31:37 -0400 Subject: [PATCH 1/3] docs: tips, tricks and links --- BEST_PRACTICES.md | 25 +++++++++++++++++++++++++ README.md | 4 +++- 2 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 BEST_PRACTICES.md diff --git a/BEST_PRACTICES.md b/BEST_PRACTICES.md new file mode 100644 index 0000000..d5e2591 --- /dev/null +++ b/BEST_PRACTICES.md @@ -0,0 +1,25 @@ +# Best Practices: tips and tricks to use Packwatch to its fullest + +## Overview + +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. + +### 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: + +- `packageSize`, representing the size of your package's archive as it is when packed using `npm pack`; +- `unpackedSize`, representing the _unpacked_ size of that package (i.e. once installed, what space do the published filed occupy on disk); +- `limit`, representing a threshold that will cause Packwatch to throw an error if crossed. + +While the `packageSize` and `unpackedSize` are automatically populated when you update Packwatch's manifest, the `limit` value can be set manually so that you leave yourself some "head room" for growth. + +#### 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. + +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. + +### 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. diff --git a/README.md b/README.md index 9bd65f1..4fce90d 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,8 @@ packwatch --update-manifest Just commit your `.packwatch.json` manifest and you're good to go! +Check out [Packwatch's best practices tips and tricks](https://github.com/mcataford/packwatch/blob/master/BEST_PRACTICES.md) for some advice on how to make the most of it! + ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)): @@ -64,4 +66,4 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d -This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! \ No newline at end of file +This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! -- 2.45.2 From c8c2d20d5922126f63f728a4255789cc5c36350f Mon Sep 17 00:00:00 2001 From: Marc Cataford Date: Fri, 1 May 2020 21:36:53 -0400 Subject: [PATCH 2/3] docs: tweaks --- BEST_PRACTICES.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/BEST_PRACTICES.md b/BEST_PRACTICES.md index d5e2591..d855c5a 100644 --- a/BEST_PRACTICES.md +++ b/BEST_PRACTICES.md @@ -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. +Got best practices questions or suggestions? Open an [issue](https://github.com/mcataford/packwatch/issues)! + ### 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: @@ -16,10 +18,10 @@ While the `packageSize` and `unpackedSize` are automatically populated when you #### 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 -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. -- 2.45.2 From cc47c8ac6d10d84ed2f754074159b4b2ed56c9f4 Mon Sep 17 00:00:00 2001 From: Marc Cataford Date: Fri, 1 May 2020 22:01:52 -0400 Subject: [PATCH 3/3] docs: first-run details --- BEST_PRACTICES.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/BEST_PRACTICES.md b/BEST_PRACTICES.md index d855c5a..bd0ad04 100644 --- a/BEST_PRACTICES.md +++ b/BEST_PRACTICES.md @@ -6,6 +6,10 @@ Monitoring the footprint of the packages you publish can be a powerful first ste Got best practices questions or suggestions? Open an [issue](https://github.com/mcataford/packwatch/issues)! +### First-run + +On the first-run, Packwatch will generate a manifest file that sets the package size and the limit to the same value. Following this, the run will return a non-zero status code. This is perfectly normal! This is meant to ensure that an initial run or a run without a manifest won't pass on CI. The next time you will run Packwatch, it will use the now-present manifest as a comparison point and proceed normally. + ### 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: -- 2.45.2