From ff3f155c828cb76eb175273e93f35ac3b05ff790 Mon Sep 17 00:00:00 2001 From: Joel Chen Date: Wed, 20 Mar 2019 09:06:50 -0700 Subject: [PATCH 1/7] doc: add draft publish guideline --- docs/drafts/PUBLISH-GUIDELINES.md | 84 +++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/drafts/PUBLISH-GUIDELINES.md diff --git a/docs/drafts/PUBLISH-GUIDELINES.md b/docs/drafts/PUBLISH-GUIDELINES.md new file mode 100644 index 00000000..22607964 --- /dev/null +++ b/docs/drafts/PUBLISH-GUIDELINES.md @@ -0,0 +1,84 @@ +# What? + +This is guidelines for publishing packages to the npm registry. + +# Why? + +After you publish your package to the public npm registry, it's visible to everyone on the internet and your users will install your package into their `node_modules`. There are a few reasons that keeping your published package tidy: + +- Security - avoid accidentally publishing your credential files like keys +- Tidiness - avoid publishing non essential temp files like `.nyc_output` or `coverage` + +# How? + +These guidelines exist to help package owners with some practices on managing packages for publishing. The primary focus is about filtering files that are published, but there are other helpful related resources as well. + +## Overview + +[npm] maintains a public registry for everyone to publish packages. Here are some related resources: + +| Purpose | How | comment | +| ------------------------------ | --------------------------- | --------------------------------------------------------- | +| bump version | [`npm version`] | This bumps version and creates git commit and tag for you | +| preview/view tarball | [`npm pack`] | Allows you to see files before or after publishing | +| publish config | [`publishConfig`] | Helpful if you need to publish to a different registry | +| publish package | [`npm publish`] | Actually publish the package | +| search/view published packages | [public registry] | [for example](https://www.npmjs.com/package/npm) | +| filter publish files | [`.npmignore`] or [`files`] | Use one base on your preference | + +## `.npmignore` or `files` + +[npm] has default ignore rules and loads from `.gitignore` but it also offer two methods for you to keep your published packages tidy. + +- blacklisting - specifying ignore files in `.npmignore` +- whitelisting - specifying files you only want to publish with `files` in your `package.json`. + +Which one to go with is solely up to you and your preference, but beware of the following gotchas and tips: + +On the `.gititnore` file: + +- [npm] automatically uses `.gitignore` if neither one exist + +On the `.npmignore` file: + +- using `.npmignore`, you could potentially publish any unintended files left in the directory. +- [npm] will stop using `.gitnore` if this exist, so beware because you may forget to add some rules to `.npmignore` after you add them to `.gitignore` + +On the `files` field in `package.json`: + +- the opposite of `.npmignore`, if you forget to add some new files to this, you could publish a package that's broken because of missing files. +- there's an open bug that [`files` affects npm's default rules](https://npm.community/t/ds-store-files-show-up-after-npm-publish/831/4) + +## Verification + +In the newer [npm] version 6, [`npm publish`] now shows the list of files published, but it doesn't offer you a chance to review them first. + +If you want to review the files, you can use the [`npm pack`] command to generate a tarball first and look inside it. + +You can also use the [`npm pack`] command to download a tarball from a published version. + +For example: `npm pack npm@6.5.0`. + +## Sources, Tests, and Docs + +A package not written in idiomatic JavaScript should be published with transpiled JavaScript as the primary executable. + +If you write your package in another language like TypeScript and you have other files like tests and extra docs, then it's your preference on whether to publish them or not. + +Keep in mind that tests is a location where someone could potentially hide malicious code to cause harm. + +## Other Resources + +There are tools that help you with the verication and publishing process: + +- https://www.npmjs.com/package/publish-please + + +[npm]: https://www.npmjs.com/ +[`npm version`]: https://docs.npmjs.com/cli/version +[`npm publish`]: https://docs.npmjs.com/cli/publish +[`npm pack`]: https://docs.npmjs.com/cli/pack +[`publishConfig`]: https://docs.npmjs.com/files/package.json#publishconfig +[public registry]: https://www.npmjs.com/ +[`.npmignore`]: https://docs.npmjs.com/misc/developers#keeping-files-out-of-your-package +[`files`]: https://docs.npmjs.com/files/package.json#files From dc0a8512e3299dca72c03cd9d9606d1bb9c34bc4 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 21 Mar 2019 09:03:04 -0700 Subject: [PATCH 2/7] Update with review Co-Authored-By: jchip --- docs/drafts/PUBLISH-GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/PUBLISH-GUIDELINES.md b/docs/drafts/PUBLISH-GUIDELINES.md index 22607964..19c44a25 100644 --- a/docs/drafts/PUBLISH-GUIDELINES.md +++ b/docs/drafts/PUBLISH-GUIDELINES.md @@ -42,7 +42,7 @@ On the `.gititnore` file: On the `.npmignore` file: - using `.npmignore`, you could potentially publish any unintended files left in the directory. -- [npm] will stop using `.gitnore` if this exist, so beware because you may forget to add some rules to `.npmignore` after you add them to `.gitignore` +- [npm] will stop using `.gitnore` if this exists, so beware because you may forget to add some rules to `.npmignore` after you add them to `.gitignore` On the `files` field in `package.json`: From 468ef57db301260bbb2399e2cee3a2e6a50fb592 Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Thu, 21 Mar 2019 09:04:44 -0700 Subject: [PATCH 3/7] Update with review Co-Authored-By: jchip --- docs/drafts/PUBLISH-GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/PUBLISH-GUIDELINES.md b/docs/drafts/PUBLISH-GUIDELINES.md index 19c44a25..a9d3ea5c 100644 --- a/docs/drafts/PUBLISH-GUIDELINES.md +++ b/docs/drafts/PUBLISH-GUIDELINES.md @@ -51,7 +51,7 @@ On the `files` field in `package.json`: ## Verification -In the newer [npm] version 6, [`npm publish`] now shows the list of files published, but it doesn't offer you a chance to review them first. +In the newer [npm] version 6, [`npm publish`] now shows the list of files published. If you want to review the files, you can use the [`npm pack`] command to generate a tarball first and look inside it. From 864a88f5e2525ba04a7dfb467bb0a2d5066e546d Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Thu, 21 Mar 2019 09:05:01 -0700 Subject: [PATCH 4/7] Update with review Co-Authored-By: jchip --- docs/drafts/PUBLISH-GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/PUBLISH-GUIDELINES.md b/docs/drafts/PUBLISH-GUIDELINES.md index a9d3ea5c..3cb81766 100644 --- a/docs/drafts/PUBLISH-GUIDELINES.md +++ b/docs/drafts/PUBLISH-GUIDELINES.md @@ -53,7 +53,7 @@ On the `files` field in `package.json`: In the newer [npm] version 6, [`npm publish`] now shows the list of files published. -If you want to review the files, you can use the [`npm pack`] command to generate a tarball first and look inside it. +If you want to review the files, you can use the [`npm pack`] command to generate a tarball first and look inside it or run `npm publish --dry-run` to get the file list. You can also use the [`npm pack`] command to download a tarball from a published version. From 4dc5c2d78f2cd04e956e1ad01036747dc661faff Mon Sep 17 00:00:00 2001 From: Joel Chen Date: Thu, 21 Mar 2019 09:27:36 -0700 Subject: [PATCH 5/7] doc: draft publish guideline review update --- docs/drafts/PUBLISH-GUIDELINES.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/drafts/PUBLISH-GUIDELINES.md b/docs/drafts/PUBLISH-GUIDELINES.md index 3cb81766..f955c6f7 100644 --- a/docs/drafts/PUBLISH-GUIDELINES.md +++ b/docs/drafts/PUBLISH-GUIDELINES.md @@ -42,30 +42,41 @@ On the `.gititnore` file: On the `.npmignore` file: - using `.npmignore`, you could potentially publish any unintended files left in the directory. -- [npm] will stop using `.gitnore` if this exists, so beware because you may forget to add some rules to `.npmignore` after you add them to `.gitignore` +- [npm] will stop using `.gitignore` if this exists, so beware because you may forget to add some rules to `.npmignore` after you add them to `.gitignore` On the `files` field in `package.json`: - the opposite of `.npmignore`, if you forget to add some new files to this, you could publish a package that's broken because of missing files. - there's an open bug that [`files` affects npm's default rules](https://npm.community/t/ds-store-files-show-up-after-npm-publish/831/4) + - The result of this is that if you have a file that npm is suppose to ignore by default within a whitelisted directory, then npm will publish it. -## Verification +## Verifications -In the newer [npm] version 6, [`npm publish`] now shows the list of files published. +Run `npm publish --dry-run` to check what you are about to publish first. In the newer [npm] version 6, [`npm publish`] now shows the list of files so you can inspect that also. -If you want to review the files, you can use the [`npm pack`] command to generate a tarball first and look inside it or run `npm publish --dry-run` to get the file list. +You can use the [`npm pack`] command to generate a tarball to see exactly what will be uploaded to the registry. You can also use the [`npm pack`] command to download a tarball from a published version. For example: `npm pack npm@6.5.0`. -## Sources, Tests, and Docs +## Transpiling Sources -A package not written in idiomatic JavaScript should be published with transpiled JavaScript as the primary executable. +A package written in another language like TypeScript should be published with transpiled JavaScript as the primary executable. -If you write your package in another language like TypeScript and you have other files like tests and extra docs, then it's your preference on whether to publish them or not. +Generally the original sources should not be required to use your published package, but it's your preference whether to publish them or not. -Keep in mind that tests is a location where someone could potentially hide malicious code to cause harm. +## Publish and Install scripts + +If your package requires any build steps such as transpiling sources, then note that [npm's recommendation](https://docs.npmjs.com/misc/scripts#best-practices) is to run those before you publish, not when your user install your package. + +The [npm scripts] `prepare` and `prepublishOnly` are intended for this purpose. + +## Tests and Docs + +For your tests and extra docs, it's your preference on whether to publish them or not. + +Keep in mind that tests generally are more relaxed at what they are allowed to do and easier to overlook, so they are a location where someone could potentially hide malicious code to cause harm. ## Other Resources @@ -82,3 +93,4 @@ There are tools that help you with the verication and publishing process: [public registry]: https://www.npmjs.com/ [`.npmignore`]: https://docs.npmjs.com/misc/developers#keeping-files-out-of-your-package [`files`]: https://docs.npmjs.com/files/package.json#files +[npm scripts]: https://docs.npmjs.com/misc/scripts#description From 03a7ee4b7817b34ec3c64c3393068568b5dedd66 Mon Sep 17 00:00:00 2001 From: Joel Chen Date: Thu, 21 Mar 2019 09:49:13 -0700 Subject: [PATCH 6/7] doc: publish guideline - more details on files bug --- docs/drafts/PUBLISH-GUIDELINES.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/drafts/PUBLISH-GUIDELINES.md b/docs/drafts/PUBLISH-GUIDELINES.md index f955c6f7..9a364021 100644 --- a/docs/drafts/PUBLISH-GUIDELINES.md +++ b/docs/drafts/PUBLISH-GUIDELINES.md @@ -48,7 +48,8 @@ On the `files` field in `package.json`: - the opposite of `.npmignore`, if you forget to add some new files to this, you could publish a package that's broken because of missing files. - there's an open bug that [`files` affects npm's default rules](https://npm.community/t/ds-store-files-show-up-after-npm-publish/831/4) - - The result of this is that if you have a file that npm is suppose to ignore by default within a whitelisted directory, then npm will publish it. + - The result is npm's default ignore rules has no effect on files under directories that are whitelisted by `files`. + - For example, if you set `"files": [ "lib" ]`, then `lib/.gitignore` will be published and there's no easy way to avoid that. ## Verifications From 30ce27f5a14294c375f49c4ae422c0ebc840e9ad Mon Sep 17 00:00:00 2001 From: Manuel Spigolon Date: Tue, 16 Apr 2019 09:11:26 -0700 Subject: [PATCH 7/7] Update docs/drafts/PUBLISH-GUIDELINES.md Co-Authored-By: jchip --- docs/drafts/PUBLISH-GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/drafts/PUBLISH-GUIDELINES.md b/docs/drafts/PUBLISH-GUIDELINES.md index 9a364021..32c71714 100644 --- a/docs/drafts/PUBLISH-GUIDELINES.md +++ b/docs/drafts/PUBLISH-GUIDELINES.md @@ -35,7 +35,7 @@ These guidelines exist to help package owners with some practices on managing pa Which one to go with is solely up to you and your preference, but beware of the following gotchas and tips: -On the `.gititnore` file: +On the `.gitignore` file: - [npm] automatically uses `.gitignore` if neither one exist