Skip to content

Commit 6acc0bc

Browse files
authored
chore(node-bundle): README touchups (#19311)
Some rephrasing after legal review. ---- *By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
1 parent ea777ce commit 6acc0bc

File tree

1 file changed

+25
-24
lines changed

1 file changed

+25
-24
lines changed

tools/@aws-cdk/node-bundle/README.md

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -3,53 +3,54 @@
33
> **NOTE:** This tool should only be used on packages in this repository,
44
> and is not intended for external usage.
55
6-
Create bundled packages with minimal dependencies and appropriate license attributions.
6+
You can use this tool to help create bundled packages with minimal dependencies and appropriate license attributions.
77

88
## Why
99

1010
When shipping nodejs applications, there is currently no easy way to ensure your users are
11-
consuming the exact dependency clojure your package was tested against.
11+
consuming the exact dependency closure your package was tested against.
1212

13-
This is because many libraries define their dependencies with a range, rather then a fixed version.
13+
This is because many libraries define their dependencies with a range, rather than a fixed version.
1414
NPM has provided an install time lock file called [shrinkwrap](https://docs.npmjs.com/cli/v8/commands/npm-shrinkwrap)
15-
to mitigate this, however, this file is only respected by NPM itself, and not by other package managers such as Yarn.
15+
to help mitigate this, however, this file is only respected by NPM itself, and not by other package managers such as Yarn.
1616

1717
## What
1818

19-
This package wires up several popular tools to offer a simple entrypoint for
19+
This package wires up several popular tools to offer a simpler entrypoint for
2020
creating self-contained nodejs packages.
2121

22-
The resulting packages are still npm installable packages, but the entrypoints you specify are
23-
replaced with a bundled version of them, embedding all their dependencies inline.
22+
The resulting packages are still npm installable packages, but you can use this tool to
23+
replace the entrypoints you specify with a bundled version of them, embedding their dependencies inline.
2424
Note that embedding dependencies means you are effectively redistributing third-party software.
25-
This could have legal/licensing implications, and typically requires proper
26-
attribution of the bundled dependencies, while validating their licenses allow
27-
such redistribution.
25+
This could have licensing implications, and it is your responsibility to provide proper
26+
and typically requires proper attribution of the bundled dependencies,
27+
while validating their licenses allow such redistribution.
2828

29-
This tool does the following:
29+
You can use this tool to help achieve the following tasks:
3030

31-
- Bundle dependencies inside the package.
31+
- Bundle the entrypoints inside the package.
3232

3333
> Currently done with [esbuild](https://esbuild.github.io), but is subject to change.
3434
35-
- Validate and create THIRD_PARTY_LICENCES files with complete third-party attributions.
35+
- Validate and create THIRD_PARTY_LICENCES file with third-party attributions for packages with declared licensing information.
3636

3737
> Currently done with [license-checker](https://www.npmjs.com/package/license-checker), but is subject to change.
3838
39-
- Enforce no circular imports are exhibited in your package, nor in your dependency closure.
39+
- Detect circular imports that are exhibited in your package, or in your dependency closure.
4040

4141
> Currently done with [madge](https://www.npmjs.com/package/madge), but is subject to change.
4242
> This is necessary because circular imports mess up the declaration order of types in the bundled file.
4343
4444
### Disclaimer
4545

46-
- Features of this package rely on the dependencies' declared licensing information, etc... and if that is incorrect, the tool may not notice/warn about that.
46+
Features of this package rely on the dependencies' declared licensing information, and the fulsomeness of
47+
the generated attribution is dependent on the dependencies’ declarations.
48+
This tool is not a substitute for your code attribution processes, but you can use it to help
49+
streamline attribution items for dependencies that have license declarations.
50+
The user of this package remains responsible for complying to their dependencies' licensing requirements,
51+
including any attribution obligations.
4752

48-
- The user of this package remains responsible for complying to their dependencies' licensing requirements.
49-
50-
- While this package makes reasonable efforts to ensure the produced THIRD_PARTY_LICENSES file is correct,
51-
the user is responsible for ensuring the output is correct (this is why it is recommended to check it into source control)
52-
If unsure, users should seek legal counsel before releasing bundled artifacts.
53+
We strongly recommend that you check all of your code into source control, and follow your ordinary code attribution processes.
5354

5455
## Alternative Approaches
5556

@@ -129,17 +130,17 @@ We recommend to integrate this tool in the following way:
129130
1. Add a `node-bundle validate` command as a post compile step.
130131
2. Set your packaging command to `node-bundle pack`.
131132

132-
This way, local dev builds will be validated not to break any functionality needed for bundling.
133+
This way, you can validate local dev builds not to break any functionality needed for bundling.
133134
In addition, developers can run `node-bundle validate --fix` to automatically fix any (fixable) violations
134-
and commit that to source code.
135+
and commit that to source control.
135136

136137
For example, if a dependency is added but the attribution file has not been re-generated,
137-
`validate` will catch this, and `validate --fix` will regenerate it.
138+
you can use `node-bundle validate` to catch this, and regenerate it with `node-bundle validate --fix`.
138139

139140
## Take into account
140141

141142
By default, the tool will use the `main` directive of the `package.json` as
142-
the entrypoint. This will ensure that all top level exports of the
143+
the entrypoint. This will help you ensure that all top level exports of the
143144
package are preserved.
144145

145146
Deep imports such as `const plugins = require('your-package/lib/plugins')` are considered

0 commit comments

Comments
 (0)