From 78dbb4b5b1bd45824f9345e0435d0071263db176 Mon Sep 17 00:00:00 2001 From: isaacs Date: Wed, 4 Jan 2012 15:09:13 -0800 Subject: [PATCH] npm@1.1.0-beta-10 --- deps/npm/Makefile | 17 ++- deps/npm/doc/cli/disputes.md | 84 ++++++++++++ deps/npm/doc/cli/faq.md | 66 +++++++--- deps/npm/doc/cli/index.md | 4 + deps/npm/doc/cli/owner.md | 1 + deps/npm/doc/cli/registry.md | 1 + deps/npm/html/api/bin.html | 2 +- deps/npm/html/api/bugs.html | 2 +- deps/npm/html/api/commands.html | 2 +- deps/npm/html/api/config.html | 2 +- deps/npm/html/api/deprecate.html | 2 +- deps/npm/html/api/docs.html | 2 +- deps/npm/html/api/edit.html | 2 +- deps/npm/html/api/explore.html | 2 +- deps/npm/html/api/help-search.html | 2 +- deps/npm/html/api/init.html | 2 +- deps/npm/html/api/install.html | 2 +- deps/npm/html/api/link.html | 2 +- deps/npm/html/api/load.html | 2 +- deps/npm/html/api/ls.html | 2 +- deps/npm/html/api/npm.html | 4 +- deps/npm/html/api/outdated.html | 2 +- deps/npm/html/api/owner.html | 2 +- deps/npm/html/api/pack.html | 2 +- deps/npm/html/api/prefix.html | 2 +- deps/npm/html/api/prune.html | 2 +- deps/npm/html/api/publish.html | 2 +- deps/npm/html/api/rebuild.html | 2 +- deps/npm/html/api/restart.html | 2 +- deps/npm/html/api/root.html | 2 +- deps/npm/html/api/run-script.html | 2 +- deps/npm/html/api/search.html | 2 +- deps/npm/html/api/start.html | 2 +- deps/npm/html/api/stop.html | 2 +- deps/npm/html/api/submodule.html | 2 +- deps/npm/html/api/tag.html | 2 +- deps/npm/html/api/test.html | 2 +- deps/npm/html/api/uninstall.html | 2 +- deps/npm/html/api/unpublish.html | 2 +- deps/npm/html/api/update.html | 2 +- deps/npm/html/api/version.html | 2 +- deps/npm/html/api/view.html | 2 +- deps/npm/html/api/whoami.html | 2 +- deps/npm/html/doc/README.html | 2 +- deps/npm/html/doc/adduser.html | 2 +- deps/npm/html/doc/bin.html | 2 +- deps/npm/html/doc/bugs.html | 2 +- deps/npm/html/doc/build.html | 2 +- deps/npm/html/doc/bundle.html | 2 +- deps/npm/html/doc/cache.html | 2 +- deps/npm/html/doc/changelog.html | 2 +- deps/npm/html/doc/coding-style.html | 2 +- deps/npm/html/doc/completion.html | 2 +- deps/npm/html/doc/config.html | 2 +- deps/npm/html/doc/deprecate.html | 2 +- deps/npm/html/doc/developers.html | 2 +- deps/npm/html/doc/disputes.html | 115 ++++++++++++++++ deps/npm/html/doc/docs.html | 2 +- deps/npm/html/doc/edit.html | 2 +- deps/npm/html/doc/explore.html | 2 +- deps/npm/html/doc/faq.html | 68 +++++++--- deps/npm/html/doc/folders.html | 2 +- deps/npm/html/doc/help-search.html | 2 +- deps/npm/html/doc/help.html | 2 +- deps/npm/html/doc/index.html | 6 +- deps/npm/html/doc/init.html | 2 +- deps/npm/html/doc/install.html | 2 +- deps/npm/html/doc/json.html | 2 +- deps/npm/html/doc/link.html | 2 +- deps/npm/html/doc/list.html | 2 +- deps/npm/html/doc/npm.html | 4 +- deps/npm/html/doc/outdated.html | 2 +- deps/npm/html/doc/owner.html | 4 +- deps/npm/html/doc/pack.html | 2 +- deps/npm/html/doc/prefix.html | 2 +- deps/npm/html/doc/prune.html | 2 +- deps/npm/html/doc/publish.html | 2 +- deps/npm/html/doc/rebuild.html | 2 +- deps/npm/html/doc/registry.html | 4 +- deps/npm/html/doc/removing-npm.html | 2 +- deps/npm/html/doc/restart.html | 2 +- deps/npm/html/doc/root.html | 2 +- deps/npm/html/doc/run-script.html | 2 +- deps/npm/html/doc/scripts.html | 2 +- deps/npm/html/doc/search.html | 2 +- deps/npm/html/doc/semver.html | 2 +- deps/npm/html/doc/star.html | 2 +- deps/npm/html/doc/start.html | 2 +- deps/npm/html/doc/stop.html | 2 +- deps/npm/html/doc/submodule.html | 2 +- deps/npm/html/doc/tag.html | 2 +- deps/npm/html/doc/test.html | 2 +- deps/npm/html/doc/uninstall.html | 2 +- deps/npm/html/doc/unpublish.html | 2 +- deps/npm/html/doc/update.html | 2 +- deps/npm/html/doc/version.html | 2 +- deps/npm/html/doc/view.html | 2 +- deps/npm/html/doc/whoami.html | 2 +- deps/npm/lib/npm.js | 51 ++++--- deps/npm/lib/utils/cmd-shim.js | 2 +- deps/npm/lib/utils/fetch.js | 2 +- deps/npm/lib/utils/ini.js | 33 +---- deps/npm/lib/utils/npm-registry-client/get.js | 4 +- deps/npm/lib/utils/read-json.js | 17 ++- deps/npm/man/man1/README.1 | 2 +- deps/npm/man/man1/adduser.1 | 2 +- deps/npm/man/man1/bin.1 | 2 +- deps/npm/man/man1/bugs.1 | 2 +- deps/npm/man/man1/build.1 | 2 +- deps/npm/man/man1/bundle.1 | 2 +- deps/npm/man/man1/cache.1 | 2 +- deps/npm/man/man1/changelog.1 | 2 +- deps/npm/man/man1/coding-style.1 | 2 +- deps/npm/man/man1/completion.1 | 2 +- deps/npm/man/man1/config.1 | 2 +- deps/npm/man/man1/deprecate.1 | 2 +- deps/npm/man/man1/developers.1 | 2 +- deps/npm/man/man1/disputes.1 | 124 ++++++++++++++++++ deps/npm/man/man1/docs.1 | 2 +- deps/npm/man/man1/edit.1 | 2 +- deps/npm/man/man1/explore.1 | 2 +- deps/npm/man/man1/faq.1 | 77 +++++++---- deps/npm/man/man1/folders.1 | 2 +- deps/npm/man/man1/help-search.1 | 2 +- deps/npm/man/man1/help.1 | 2 +- deps/npm/man/man1/index.1 | 5 +- deps/npm/man/man1/init.1 | 2 +- deps/npm/man/man1/install.1 | 2 +- deps/npm/man/man1/json.1 | 2 +- deps/npm/man/man1/link.1 | 2 +- deps/npm/man/man1/list.1 | 2 +- deps/npm/man/man1/npm.1 | 4 +- deps/npm/man/man1/outdated.1 | 2 +- deps/npm/man/man1/owner.1 | 5 +- deps/npm/man/man1/pack.1 | 2 +- deps/npm/man/man1/prefix.1 | 2 +- deps/npm/man/man1/prune.1 | 2 +- deps/npm/man/man1/publish.1 | 2 +- deps/npm/man/man1/rebuild.1 | 2 +- deps/npm/man/man1/registry.1 | 5 +- deps/npm/man/man1/removing-npm.1 | 2 +- deps/npm/man/man1/restart.1 | 2 +- deps/npm/man/man1/root.1 | 2 +- deps/npm/man/man1/run-script.1 | 2 +- deps/npm/man/man1/scripts.1 | 2 +- deps/npm/man/man1/search.1 | 2 +- deps/npm/man/man1/semver.1 | 2 +- deps/npm/man/man1/star.1 | 2 +- deps/npm/man/man1/start.1 | 2 +- deps/npm/man/man1/stop.1 | 2 +- deps/npm/man/man1/submodule.1 | 2 +- deps/npm/man/man1/tag.1 | 2 +- deps/npm/man/man1/test.1 | 2 +- deps/npm/man/man1/uninstall.1 | 2 +- deps/npm/man/man1/unpublish.1 | 2 +- deps/npm/man/man1/update.1 | 2 +- deps/npm/man/man1/version.1 | 2 +- deps/npm/man/man1/view.1 | 2 +- deps/npm/man/man1/whoami.1 | 2 +- deps/npm/man/man3/bin.3 | 2 +- deps/npm/man/man3/bugs.3 | 2 +- deps/npm/man/man3/commands.3 | 2 +- deps/npm/man/man3/config.3 | 2 +- deps/npm/man/man3/deprecate.3 | 2 +- deps/npm/man/man3/docs.3 | 2 +- deps/npm/man/man3/edit.3 | 2 +- deps/npm/man/man3/explore.3 | 2 +- deps/npm/man/man3/help-search.3 | 2 +- deps/npm/man/man3/init.3 | 2 +- deps/npm/man/man3/install.3 | 2 +- deps/npm/man/man3/link.3 | 2 +- deps/npm/man/man3/load.3 | 2 +- deps/npm/man/man3/ls.3 | 2 +- deps/npm/man/man3/npm.3 | 4 +- deps/npm/man/man3/outdated.3 | 2 +- deps/npm/man/man3/owner.3 | 2 +- deps/npm/man/man3/pack.3 | 2 +- deps/npm/man/man3/prefix.3 | 2 +- deps/npm/man/man3/prune.3 | 2 +- deps/npm/man/man3/publish.3 | 2 +- deps/npm/man/man3/rebuild.3 | 2 +- deps/npm/man/man3/restart.3 | 2 +- deps/npm/man/man3/root.3 | 2 +- deps/npm/man/man3/run-script.3 | 2 +- deps/npm/man/man3/search.3 | 2 +- deps/npm/man/man3/start.3 | 2 +- deps/npm/man/man3/stop.3 | 2 +- deps/npm/man/man3/submodule.3 | 2 +- deps/npm/man/man3/tag.3 | 2 +- deps/npm/man/man3/test.3 | 2 +- deps/npm/man/man3/uninstall.3 | 2 +- deps/npm/man/man3/unpublish.3 | 2 +- deps/npm/man/man3/update.3 | 2 +- deps/npm/man/man3/version.3 | 2 +- deps/npm/man/man3/view.3 | 2 +- deps/npm/man/man3/whoami.3 | 2 +- .../node_modules/fstream/lib/link-writer.js | 1 + deps/npm/node_modules/fstream/package.json | 2 +- deps/npm/node_modules/tar/lib/pack.js | 4 +- deps/npm/node_modules/tar/package.json | 2 +- deps/npm/package.json | 2 +- deps/npm/scripts/install.sh | 52 ++++++-- deps/npm/scripts/release.sh | 40 ++++++ deps/npm/test/run.js | 7 +- 204 files changed, 835 insertions(+), 326 deletions(-) create mode 100644 deps/npm/doc/cli/disputes.md create mode 100644 deps/npm/html/doc/disputes.html create mode 100644 deps/npm/man/man1/disputes.1 create mode 100644 deps/npm/scripts/release.sh diff --git a/deps/npm/Makefile b/deps/npm/Makefile index 20686da009..7d3e106535 100644 --- a/deps/npm/Makefile +++ b/deps/npm/Makefile @@ -108,18 +108,29 @@ version: link git add package.json &&\ git ci -m v$(shell npm -v) -publish: link +publish: link doc + git tag -d v$(shell npm -v) || true + git push origin :v$(shell npm -v) || true + npm unpublish npm@$(shell npm -v) || true git tag -s -m v$(shell npm -v) v$(shell npm -v) &&\ git push origin --tags &&\ npm publish &&\ - make doc-publish + npm tag npm@$(shell npm -v) $(shell npm -v | awk -F. '{print $$1 "." $$2}') &&\ + make doc-publish &&\ + make zip-publish docpublish: doc-publish doc-publish: doc rsync -vazu --stats --no-implied-dirs --delete html/doc/ npmjs.org:/var/www/npmjs.org/public/doc rsync -vazu --stats --no-implied-dirs --delete html/api/ npmjs.org:/var/www/npmjs.org/public/api +zip-publish: release + scp release/*.zip npmjs.org:/var/www/npmjs.org/public/dist/ + +release: + @bash scripts/release.sh + sandwich: @[ $$(whoami) = "root" ] && (echo "ok"; echo "ham" > sandwich) || echo "make it yourself" -.PHONY: all latest install dev link doc clean uninstall test man doc-publish doc-clean docclean docpublish +.PHONY: all latest install dev link doc clean uninstall test man doc-publish doc-clean docclean docpublish release zip-publish diff --git a/deps/npm/doc/cli/disputes.md b/deps/npm/doc/cli/disputes.md new file mode 100644 index 0000000000..96ad9ef1f8 --- /dev/null +++ b/deps/npm/doc/cli/disputes.md @@ -0,0 +1,84 @@ +npm-disputes(1) -- Handling Module Name Disputes +================================================ + +## SYNOPSIS + +1. Get the author email with `npm owner ls ` +1. Email the author, CC . +2. After a few weeks, if there's no resolution, we'll sort it out. + +## DESCRIPTION + +There sometimes arise cases where a user publishes a module, and then +later, some other user wants to use that name. Here are some common +ways that happens (each of these is based on actual events.) + +1. Bob writes a JavaScript module `foo`, which is not node-specific. + Bob doesn't use node at all. Joe wants to use `foo` in node, so he + wraps it in an npm module. Some time later, Bob starts using node, + and wants to take over management of his program. +2. Bob writes an npm module `foo`, and publishes it. Perhaps much + later, Joe finds a bug in `foo`, and fixes it. He sends a pull + request to Bob, but Bob doesn't have the time to deal with it, + because he has a new job and a new baby and is focused on his new + erlang project, and kind of not involved with node any more. Joe + would like to publish a new `foo`, but can't, because the name is + taken. +3. Bob writes a 10-line flow-control library, and calls it `foo`, and + publishes it to the npm registry. Being a simple little thing, it + never really has to be updated. Joe works for Foo Inc, the makers + of the critically acclaimed and widely-marketed `foo` JavaScript + toolkit framework. They publish it to npm as `foojs`, but people are + routinely confused when `npm install foo` is some different thing. +4. Bob writes a parser for the widely-known `foo` file format, because + he needs it for work. Then, he gets a new job, and never updates the + prototype. Later on, Joe writes a much more complete `foo` parser, + but can't publish, because Bob's `foo` is in the way. + +The validity of Joe's claim in each situation can be debated. However, +Joe's appropriate course of action in each case is the same. + +1. `npm owner ls foo`. This will tell Joe the email address of the + owner (Bob). +2. Joe emails Bob, explaining the situation **as respecfully as possible**, + and what he would like to do with the module name. He adds + isaacs to the CC list of the email. Mention in the email + that Bob can run `npm owner add joe foo` to add Joe as an owner of + the `foo` package. +3. After a reasonable amount of time, if Bob has not responded, or if + Bob and Joe can't come to any sort of resolution, email isaacs + and we'll sort it out. + +## REASONING + +In almost every case so far, the parties involved have been able to reach +an amicable resolution without any major intervention. Most people +really do want to be reasonable, and are probably not even aware that +they're in your way. + +Module ecosystems are most vibrant and powerful when they are as +self-directed as possible. If an admin one day deletes something you +had worked on, then that is going to make most people quite upset, +regardless of the justification. When humans solve their problems by +talking to other humans with respect, everyone has the chance to end up +feeling good about the interaction. + +## EXCEPTIONS + +Some things are not allowed, and will be removed without discussion if +they are brought to the attention of the npm registry admins, including +but not limited to: + +1. Malware (that is, a module designed to exploit or harm the machine on + which it is installed) +2. Violations of copyright or licenses (for example, cloning an + MIT-licensed program, and then removing or changing the copyright and + license statement) +3. Illegal content. + +If you see bad behavior like this, please report it right away. + +## SEE ALSO + +* npm-registry(1) +* npm-owner(1) diff --git a/deps/npm/doc/cli/faq.md b/deps/npm/doc/cli/faq.md index 15bb0c637d..938338c22b 100644 --- a/deps/npm/doc/cli/faq.md +++ b/deps/npm/doc/cli/faq.md @@ -32,35 +32,65 @@ tl;dr: something with the `-g` flag, then its executables go in `npm bin -g` and its modules go in `npm root -g`. -## How do I install something everywhere? +## How do I install something on my computer in a central location? -Install it globally by tacking `-g` or `--global` to the command. +Install it globally by tacking `-g` or `--global` to the command. (This +is especially important for command line utilities that need to add +their bins to the global system `PATH`.) ## I installed something globally, but I can't `require()` it Install it locally. -## I don't wanna. +The global install location is a place for command-line utilities +to put their bins in the system `PATH`. It's not for use with `require()`. -Check out `npm link`. You might like it. +If you `require()` a module in your code, then that means it's a +dependency, and a part of your program. You need to install it locally +in your program. -## No, I really want 0.x style 'everything global' style. +## Why can't npm just put everything in one place, like other package managers? -Ok, fine. Do this: +Not every change is an improvement, but every improvement is a change. +This would be like asking git to do network IO for every commit. It's +not going to happen, because it's a terrible idea that causes more +problems than it solves. - echo 'export NODE_PATH="'$(npm root -g)'"' >> ~/.bashrc - . ~/.bashrc - npm config set global true +It is much harder to avoid dependency conflicts without nesting +dependencies. This is fundamental to the way that npm works, and has +proven to be an extremely successful approach. See `npm-folders(1)` for +more details. -This is not recommended. +If you want a package to be installed in one place, and have all your +programs reference the same copy of it, then use the `npm link` command. +That's what it's for. Install it globally, then link it into each +program that uses it. -Many things **will not work** if you do this. Make sure you read and -understand `npm-config(1)` and `npm-global(1)` before you complain -about things being broken. +## Whatever, I really want the old style 'everything global' style. -When you realize what a mistake it was, do this to switch back: +Write your own package manager, then. It's not that hard. - npm config delete global --local +npm will not help you do something that is known to be a bad idea. + +## Should I check my `node_modules` folder into git? + +Mikeal Rogers answered this question very well: + + + +tl;dr + +* Check `node_modules` into git for things you **deploy**, such as + websites and apps. +* Do not check `node_modules` into git for libraries and modules + intended to be reused. +* Use npm to manage dependencies in your dev environment, but not in + your deployment scripts. + +## Is it 'npm' or 'NPM' or 'Npm'? + +npm should never be capitalized unless it is being displayed in a +location that is customarily all-caps (such as the title of man pages.) ## If 'npm' is an acronym, why is it never capitalized? @@ -73,7 +103,7 @@ acronym, and thus incorrectly named.) National Association of Pastoral Musicians. You can learn more about them at . -In software, "NPM" is a non-parametric mapping utility written by +In software, "NPM" is a Non-Parametric Mapping utility written by Chris Rorden. You can analyze pictures of brains with it. Learn more about the (capitalized) NPM program at . @@ -186,11 +216,9 @@ Go to . ## I get ECONNREFUSED a lot. What's up? Either the registry is down, or node's DNS isn't able to reach out. -This happens a lot if you don't follow *all* the steps in the Cygwin -setup doc. To check if the registry is down, open up - + in a web browser. This will also tell you if you are just unable to access the internet for some reason. diff --git a/deps/npm/doc/cli/index.md b/deps/npm/doc/cli/index.md index b355042df0..5a9b99be19 100644 --- a/deps/npm/doc/cli/index.md +++ b/deps/npm/doc/cli/index.md @@ -54,6 +54,10 @@ npm-index(1) -- Index of all npm documentation Developer Guide +## npm-disputes(1) + + Handling Module Name Disputes + ## npm-docs(1) Docs for a package in a web browser maybe diff --git a/deps/npm/doc/cli/owner.md b/deps/npm/doc/cli/owner.md index 8365da379e..902e083fca 100644 --- a/deps/npm/doc/cli/owner.md +++ b/deps/npm/doc/cli/owner.md @@ -30,3 +30,4 @@ that is not implemented at this time. * npm-publish(1) * npm-registry(1) * npm-adduser(1) +* npm-disputes(1) diff --git a/deps/npm/doc/cli/registry.md b/deps/npm/doc/cli/registry.md index 13c872494c..44ddd94e05 100644 --- a/deps/npm/doc/cli/registry.md +++ b/deps/npm/doc/cli/registry.md @@ -90,3 +90,4 @@ Stay tuned! * npm-config(1) * npm-developers(1) +* npm-disputes(1) diff --git a/deps/npm/html/api/bin.html b/deps/npm/html/api/bin.html index b54352f0b0..a5bd3325c4 100644 --- a/deps/npm/html/api/bin.html +++ b/deps/npm/html/api/bin.html @@ -19,7 +19,7 @@

This function should not be used programmatically. Instead, just refer to the npm.bin member.

- + + diff --git a/deps/npm/html/doc/docs.html b/deps/npm/html/doc/docs.html index 212fabb996..7c0d94d7da 100644 --- a/deps/npm/html/doc/docs.html +++ b/deps/npm/html/doc/docs.html @@ -37,7 +37,7 @@ config param.

- +