diff options
| -rw-r--r-- | CONTRIBUTING.md | 4 | ||||
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | TROUBLESHOOTING.md | 192 | ||||
| -rwxr-xr-x | bin/npm-cli.js | 2 | ||||
| -rw-r--r-- | doc/cli/npm-install.md | 16 | ||||
| -rw-r--r-- | doc/cli/npm.md | 40 | ||||
| -rw-r--r-- | doc/files/package.json.md | 26 | ||||
| -rw-r--r-- | doc/misc/npm-disputes.md | 2 | ||||
| -rw-r--r-- | package.json | 4 |
9 files changed, 43 insertions, 245 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f85afbbe2..f412dc93e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,15 +59,15 @@ Collaborators who become inactive for 3 months or longer may have their collabor * Only answer questions when they know the answer, and provide a reference to the answer. * If collaborators aren't totally confident about their answer, please leave the issue and try another one. * If they've responded to an issue, it becomes their responsibility to see it to resolution. -* Close issues if there's no response within a month. * Defer to fellow Collaborators & npm employees for answers (Again, please don't @ collaborators or npm employees, thank you!) -* Make sure to search for [the troubleshooting doc](./TROUBLESHOOTING.md) and search on the issue tracker for similar issues before opening a new one. +* Make sure to search [the troubleshooting posts on npm.community](https://npm.community/c/support/troubleshooting) and search the rest of the forum for similar topics. ### npm, Inc Employees Folks who work at npm, Inc, who have a responsibility to ensure the stability and functionality of the tools npm offers. #### Abilities + * Label/triage new issues * Respond to ongoing issues * Close resolved issues @@ -153,7 +153,7 @@ you should [read this](https://docs.npmjs.com/misc/developers). When you find issues, please report them: * web: - <https://github.com/npm/npm/issues> + <https://npm.community/c/bugs> Be sure to include *all* of the output from the npm command that didn't work as expected. The `npm-debug.log` file is also helpful to provide. diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md deleted file mode 100644 index 0320075c5..000000000 --- a/TROUBLESHOOTING.md +++ /dev/null @@ -1,192 +0,0 @@ -# Troubleshooting Common Issues - -## Using this Document - -Search for the error message you're getting and see if there's a match, or skim the [table of contents](#table-of-contents) below for topics that seem relevant to the issue you're having. Each issue section has steps to work around or fix the particular issue, and have examples of common error messages. - -If you do not find the issue below, try searching the issue tracker itself for potential duplicates before opening a new issue. - -If you're reading this document because you noticed an issue with npm's web site, please let the [web team](https://github.com/npm/www/issues) know. - -### Updating this Document - -If you think something should be added here, make a PR that includes the following: - -0. a summary -0. one or more example errors -0. steps to debug and fix -0. links to at least one related issue from the tracker - -For more details of the content and formatting of these entries, refer to examples below. - -## Table of Contents - -* [Upgrading npm](#upgrading-npm) -* [Proxies and Networking](#proxy-and-networking-issues) -* [Cannot find module](#cannot-find-module) -* [Shasum Check Fails](#shasum-check-fails) -* [No Git](#no-git) - -## Upgrading npm - -Whenever you get npm errors, it's a good idea to first check your npm version and upgrade to latest whenever possible. We still see people running npm@1 (!) and in those cases, installing the latest version of npm usually solves the problem. - -You can check your npm version by running `npm -v`. - -### Steps to Fix -* Upgrading on \*nix (OSX, Linux, etc.) - -(You may need to prefix these commands with sudo, especially on Linux, or OS X if you installed Node using its default installer.) -You can upgrade to the latest version of npm using: -`npm install -g npm@latest` -Or upgrade to the most recent LTS release: -`npm install -g npm@lts` - -* Upgrading on Windows - -We have a [detailed guide](https://github.com/npm/npm/wiki/Troubleshooting#upgrading-on-windows) for upgrading on windows on our wiki. - -## Proxy and Networking Issues - -npm might not be able to connect to the registry for various reasons. Perhaps your machine is behind a firewall that needs to be opened, or you require a corporate proxy to access the npm registry. This issue can manifest in a wide number of different ways. Usually, strange network errors are an instance of this specific problem. - -Sometimes, users may have install failures due to Git/Github access issues. Git/GitHub access is separate from npm registry access. For users in some locations (India in particular), problems installing packages may be due to connectivity problems reaching GitHub and not the npm registry. - -If you believe your network is configured and working correctly, and you're still having problems installing, please let the [registry team](https://github.com/npm/registry/issues) know you're having trouble. - -### Steps to Fix - -0. Make sure you have a working internet connection. Can you reach https://registry.npmjs.org? Can you reach other sites? If other sites are unreachable, this is not a problem with npm. - -0. Check http://status.npmjs.org/ for any potential current service outages. - -0. If your company has a process for domain whitelisting for developers, make sure https://registry.npmjs.org is a whitelisted domain. - -0. If you're in China, consider using https://npm.taobao.org/ as a registry, which sits behind the Firewall. - -0. On Windows, npm does not access proxies configured at the system level, so you need to configure them manually in order for npm to access them. Make sure [you have added the appropriate proxy configuration to `.npmrc`](https://docs.npmjs.com/misc/config#https-proxy). - -0. If you already have a proxy configured, it might be configured incorrectly or use the wrong credentials. Verify your credentials, test the specific credentials with a separate application. - -0. The proxy itself, on the server, might also have a configuration error. In this case, you'll need to work with your system administrator to verify that the proxy, and HTTPS, are configured correctly. You may test it by running regular HTTPS requests. - -### Example Errors - -This error can manifest in a wide range of different ways: - -``` -npm ERR! code UNABLE_TO_VERIFY_LEAF_SIGNATURE -npm ERR! unable to verify the first certificate -``` -``` -npm ERR! code UNABLE_TO_GET_ISSUER_CERT_LOCALLY -npm ERR! unable to get local issuer certificate -``` -``` -npm ERR! code DEPTH_ZERO_SELF_SIGNED_CERT -npm ERR! self signed certificate -``` -``` -124 error code ECONNREFUSED -125 error errno ECONNREFUSED -126 error syscall connect -``` -``` -136 error Unexpected token < -136 error <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> -136 error <HTML><HEAD><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> -136 error <TITLE>ERROR: Cache Access Denied</TITLE> -``` -``` -31 verbose stack Error: connect ETIMEDOUT 123.123.123.123:443 -``` -``` -108 error code EAI_AGAIN -109 error errno EAI_AGAIN -110 error syscall getaddrinfo -111 error getaddrinfo EAI_AGAIN proxy.yourcorp.com:811 -``` -``` -npm ERR! Error: getaddrinfo ESRCH -npm ERR! at errnoException (dns.js:37:11) -npm ERR! at Object.onanswer as oncomplete -``` -``` -35 error Unexpected token u -35 error function FindProxyForURL(url, host) { -``` - -### Related issues -* [#14318](https://github.com/npm/npm/issues/14318) -* [#15059](https://github.com/npm/npm/issues/15059) -* [#14336](https://github.com/npm/npm/issues/14336) - -## Cannot find module - -If *when running npm* (not your application), you get an error about a module not being found, this almost certainly means that there's something wrong with your npm installation. - -If this happens when trying to start your application, you might not have installed your package's dependencies yet. - -### Steps to Fix - -0. If this happens when you try to start your application, try running `npm install` to install the app's dependencies. Make sure all its actual dependencies are listed in `package.json` - -0. If this happens on any npm command, please reinstall. - -### Examples - -``` -module.js:338 - throw err; - ^ -Error: Cannot find module -``` -### Related Issues - -* [#14699](https://github.com/npm/npm/issues/14699) - -## Shasum Check Fails - -This is a common issue which used to be caused by caching issues. Nowadays, the cache has been improved, so it's likely to be an install issue, which can be caused by network problems (sometimes even [proxy issues](#proxy-and-networking-issues)), a node bug, or possibly some sort of npm bug. - -### Steps to Fix - -0. Try running `npm install` again. It may have been a momentary hiccup or corruption during package download. - -0. Check http://status.npmjs.org/ for any potential current service outages. - -0. If the shasum error specifically has `Actual: da39a3ee5e6b4b0d3255bfef95601890afd80709`, with this exact shasum, it means the package download was empty, which is certainly a networking issue. - -0. Make sure your [network connection and proxy settings](#proxy-and-networking-issues) are ok. - -0. Update your node version to the latest stable version. - -### Examples - -``` -npm ERR! shasum check failed for C:\Users\some-user\AppData\Local\Temp\npm-9356-7 -d74e411\registry.npmjs.org\some-package\-\some-package-1.0.0.tgz -npm ERR! Expected: 652294c14651db29fa93bd2d5ff2983a4f08c636 -npm ERR! Actual: c45474b40e6a7474633ec6f2b0315feaf15c61f2 -npm ERR! From: https://registry.npmjs.org/some-package/-/some-package-1.0.0.tgz -``` - -### Related Issues -* [#14720](https://github.com/npm/npm/issues/14720) -* [#13405](https://github.com/npm/npm/issues/13405) - -## No Git -If your install fails and you see a message saying you don't have git installed, it should be resolved by installing git. - -### Steps to Fix - -0. [Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) following the instructions for your machine. - -### Examples - -npm ERR! not found: git -ENOGIT - -### Related Issues - -* [#11095](https://github.com/npm/npm/issues/11095) diff --git a/bin/npm-cli.js b/bin/npm-cli.js index b5cf4e312..a38009d27 100755 --- a/bin/npm-cli.js +++ b/bin/npm-cli.js @@ -103,7 +103,7 @@ break } } - const changelog = `https://github.com/npm/npm/releases/tag/v${latest}` + const changelog = `https://github.com/npm/cli/releases/tag/v${latest}` notifier.notify({ message: `New ${type} version of ${pkg.name} available! ${ useColor ? color.red(old) : old diff --git a/doc/cli/npm-install.md b/doc/cli/npm-install.md index 7eb8608a8..a349e5862 100644 --- a/doc/cli/npm-install.md +++ b/doc/cli/npm-install.md @@ -54,7 +54,7 @@ after packing it up into a tarball (b). With the `--production` flag (or when the `NODE_ENV` environment variable is set to `production`), npm will not install modules listed in `devDependencies`. - + > NOTE: The `--production` flag has no particular meaning when adding a dependency to a project. @@ -69,8 +69,8 @@ after packing it up into a tarball (b). Install a package that is sitting on the filesystem. Note: if you just want to link a dev directory into your npm root, you can do this more easily by - using `npm link`. - + using `npm link`. + Tarball requirements: * The filename *must* use `.tar`, `.tar.gz`, or `.tgz` as the extension. @@ -223,11 +223,11 @@ after packing it up into a tarball (b). Examples: - npm install git+ssh://git@github.com:npm/npm.git#v1.0.27 - npm install git+ssh://git@github.com:npm/npm#semver:^5.0 - npm install git+https://isaacs@github.com/npm/npm.git - npm install git://github.com/npm/npm.git#v1.0.27 - GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/npm.git + npm install git+ssh://git@github.com:npm/cli.git#v1.0.27 + npm install git+ssh://git@github.com:npm/cli#semver:^5.0 + npm install git+https://isaacs@github.com/npm/cli.git + npm install git://github.com/npm/cli.git#v1.0.27 + GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git * `npm install <githubname>/<githubrepo>[#<commit-ish>]`: * `npm install github:<githubname>/<githubrepo>[#<commit-ish>]`: diff --git a/doc/cli/npm.md b/doc/cli/npm.md index e41e7252e..82f78a0f9 100644 --- a/doc/cli/npm.md +++ b/doc/cli/npm.md @@ -53,10 +53,10 @@ See `npm-folders(5)` to learn about where npm puts stuff. In particular, npm has two modes of operation: -* global mode: +* global mode: npm installs packages into the install prefix at `prefix/lib/node_modules` and bins are installed in `prefix/bin`. -* local mode: +* local mode: npm installs packages into the current project directory, which defaults to the current working directory. Packages are installed to `./node_modules`, and bins are installed to `./node_modules/.bin`. @@ -90,24 +90,24 @@ following help topics: npm is extremely configurable. It reads its configuration options from 5 places. -* Command line switches: +* Command line switches: Set a config with `--key val`. All keys take a value, even if they are booleans (the config parser doesn't know what the options are at the time of parsing). If no value is provided, then the option is set to boolean `true`. -* Environment Variables: +* Environment Variables: Set any config by prefixing the name in an environment variable with `npm_config_`. For example, `export npm_config_key=val`. -* User Configs: +* User Configs: The file at $HOME/.npmrc is an ini-formatted list of configs. If present, it is parsed. If the `userconfig` option is set in the cli or env, then that will be used instead. -* Global Configs: +* Global Configs: The file found at ../etc/npmrc (from the node executable, by default this resolves to /usr/local/etc/npmrc) will be parsed if it is found. If the `globalconfig` option is set in the cli, env, or user config, then that file is parsed instead. -* Defaults: +* Defaults: npm's default configuration options are defined in lib/utils/config-defs.js. These must not be changed. @@ -117,34 +117,24 @@ See `npm-config(7)` for much much more information. Patches welcome! -* code: - Read through `npm-coding-style(7)` if you plan to submit code. - You don't have to agree with it, but you do have to follow it. -* docs: - If you find an error in the documentation, edit the appropriate markdown - file in the "doc" folder. (Don't worry about generating the man page.) - -Contributors are listed in npm's `package.json` file. You can view them -easily by doing `npm view npm contributors`. - If you would like to contribute, but don't know what to work on, read the contributing guidelines and check the issues list. -* https://github.com/npm/npm/wiki/Contributing-Guidelines -* <https://github.com/npm/npm/issues> +* [CONTRIBUTING.md](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) +* [Bug tracker](https://npm.community/c/bugs) +* [Support tracker](https://npm.community/c/support) ## BUGS When you find issues, please report them: * web: - <https://github.com/npm/npm/issues> - -Be sure to include *all* of the output from the npm command that didn't work -as expected. The `npm-debug.log` file is also helpful to provide. + <https://npm.community/c/bugs> -You can also look for isaacs in #node.js on irc://irc.freenode.net. He -will no doubt tell you to put the output in a gist or email. +Be sure to follow the template and bug reporting guidelines. You can also ask +for help in the [support forum](https://npm.community/c/support) if you're +unsure if it's actually a bug or are having trouble coming up with a detailed +reproduction to report. ## AUTHOR diff --git a/doc/files/package.json.md b/doc/files/package.json.md index 9fa17f746..d1fbe5254 100644 --- a/doc/files/package.json.md +++ b/doc/files/package.json.md @@ -11,10 +11,10 @@ settings described in `npm-config(7)`. ## name -If you plan to publish your package, the *most* important things in your -package.json are the name and version fields as they will be required. The name -and version together form an identifier that is assumed to be completely unique. -Changes to the package should come along with changes to the version. If you don't +If you plan to publish your package, the *most* important things in your +package.json are the name and version fields as they will be required. The name +and version together form an identifier that is assumed to be completely unique. +Changes to the package should come along with changes to the version. If you don't plan to publish your package, the name and version fields are optional. The name is what your thing is called. @@ -44,10 +44,10 @@ A name can be optionally prefixed by a scope, e.g. `@myorg/mypackage`. See ## version -If you plan to publish your package, the *most* important things in your -package.json are the name and version fields as they will be required. The name -and version together form an identifier that is assumed to be completely unique. -Changes to the package should come along with changes to the version. If you don't +If you plan to publish your package, the *most* important things in your +package.json are the name and version fields as they will be required. The name +and version together form an identifier that is assumed to be completely unique. +Changes to the package should come along with changes to the version. If you don't plan to publish your package, the name and version fields are optional. Version must be parseable by @@ -368,7 +368,7 @@ Do it like this: "repository" : { "type" : "git" - , "url" : "https://github.com/npm/npm.git" + , "url" : "https://github.com/npm/cli.git" } "repository" : @@ -490,10 +490,10 @@ specified, then `master` is used. Examples: - git+ssh://git@github.com:npm/npm.git#v1.0.27 - git+ssh://git@github.com:npm/npm#semver:^5.0 - git+https://isaacs@github.com/npm/npm.git - git://github.com/npm/npm.git#v1.0.27 + git+ssh://git@github.com:npm/cli.git#v1.0.27 + git+ssh://git@github.com:npm/cli#semver:^5.0 + git+https://isaacs@github.com/npm/cli.git + git://github.com/npm/cli.git#v1.0.27 ### GitHub URLs diff --git a/doc/misc/npm-disputes.md b/doc/misc/npm-disputes.md index d247cf05b..2d8885ecf 100644 --- a/doc/misc/npm-disputes.md +++ b/doc/misc/npm-disputes.md @@ -114,7 +114,7 @@ metadata. ## CHANGES This is a living document and may be updated from time to time. Please refer to -the [git history for this document](https://github.com/npm/npm/commits/master/doc/misc/npm-disputes.md) +the [git history for this document](https://github.com/npm/cli/commits/latest/doc/misc/npm-disputes.md) to view the changes. ## LICENSE diff --git a/package.json b/package.json index a3598b992..c985242aa 100644 --- a/package.json +++ b/package.json @@ -16,10 +16,10 @@ "author": "Isaac Z. Schlueter <i@izs.me> (http://blog.izs.me)", "repository": { "type": "git", - "url": "https://github.com/npm/npm" + "url": "https://github.com/npm/cli" }, "bugs": { - "url": "https://github.com/npm/npm/issues" + "url": "https://npm.community/c/bugs" }, "directories": { "bin": "./bin", |