diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e3512ffeaec..7e2890140bb0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,191 +1,56 @@ -# npm CLI Contributor Roles and Responsibilities +# Contributing -## Table of Contents +## Code of Conduct -* [Introduction](#introduction) -* [Code Structure](#code-structure) -* [Running Tests](#running-tests) -* [Debugging](#debugging) -* [Coverage](#coverage) -* [Benchmarking](#benchmarking) -* [Types of Contributions](#types-of-contributions) - * [Contributing an Issue?](#contributing-an-issue) - * [Contributing a Question?](#contributing-a-question) - * [Contributing a Bug Fix?](#contributing-a-bug-fix) - * [Contributing a Feature?](#contributing-a-bug-feature) -* [Development Dependencies](#development-dependencies) -* [Dependencies](#dependencies) +All interactions in the **npm** organization on GitHub are considered to be covered by our standard [Code of Conduct](https://www.npmjs.com/policies/conduct). -## Introduction +## Development -Welcome to the npm CLI Contributor Guide! This document outlines the npm CLI repository's process for community interaction and contribution. This includes the issue tracker, pull requests, wiki pages, and, to a certain extent, outside communication in the context of the npm CLI. This is an entry point for anyone wishing to contribute their time and effort to making npm a better tool for the JavaScript community! +**1. Clone this repository...** -All interactions in the npm repository are covered by the [npm Code of Conduct](https://www.npmjs.com/policies/conduct) +```bash +$ git clone git@github.com:npm/cli.git +``` +**2. Navigate into project & install development-specific dependencies...** -## Code Structure -``` -/ -├── bin/ -│ │ # Directory for executable files. It's very rare that you -│ │ # will need to update a file in this directory. -│ │ -│ ├── npm # npm-cli entrypoint for bourne shell -│ ├── npm-cli.js # npm-cli entrypoint for node -│ ├── npm.cmd # npm-cli entrypoint for windows -│ ├── npx # npx entrypoint for bourne shell -│ ├── npx-cli.js # npx entrypoint for node -│ └── npx.cmd # npx entrypoint for windows -│ -├── docs/ 📖 -│ │ # Directory that contains the documentation website for -│ │ # the npm-cli. You can run this website locally, and have -│ │ # offline docs! 🔥📖🤓 -│ │ -│ ├── content/ # Markdown files for site content -│ ├── src/ # Source files for the website; gatsby related -│ └── package.json # Site manifest; scripts and dependencies -│ -├── lib/ 📦 -│ # All the Good Bits(tm) of the CLI project live here -│ -├── node_modules/ 🔋 -│ # Vendored dependencies for the CLI project (See the -│ # dependencies section below for more details). -│ -├── scripts/ 📜 -│ # We've created some helper scripts for working with the -│ # CLI project, specifically around managing our vendored -│ # dependencies, merging in pull-requests, and publishing -│ # releases. -│ -├── test/ 🧪 -│ # All the tests for the CLI live in this folder. We've -│ # got a lot of tests 🤓🧪🩺 -│ -├── CONTRIBUTING.md # This file! 🎉 -└── package.json # The projects main manifest file 📃 +```bash +$ cd ./npm && npm install ``` -## Running Tests +**3. Write some code &/or add some tests...** +```bash +... ``` -# Make sure you install the dependencies first before running tests. -$ npm install -# Run tests for the CLI (it could take a while). -$ npm run test +**4. Run tests & ensure they pass...** ``` - -## Debugging - -It can be tricky to track down issues in the CLI. It's a large code base that has been evolving for over a decade. There is a handy `make` command that will connect the **cloned repository** you have on your machine with the global command, so you can add `console.log` statements or debug any other way you feel most comfortable with. - +$ npm run test ``` -# Clone the repository to start with -$ git clone git@github.com:npm/cli.git -# Change working directories into the repository -$ cd cli +**5. Open a [Pull Request](https://github.com/npm/cli/pulls) for your work & become the newest conributor to `npm`! 🎉** -# Make sure you have the latest code (if that's what you're trying to debug) -$ git fetch origin latest +## Test Coverage -# Connect repository to the global namespace -$ make link +We expect that every new feature or bug fix comes with corresponding tests that validate the solutions. We strive to have as close to, if not exactly, 100% code coverage. -################# -# ALTERNATIVELY -################# -# If you're working on a feature or bug, you can run the same command on your -# working branch and link that code. +**You can find out what the current test coverage percentage is by running...** -# Create new branch to work from (there are many ways) -$ git checkout -b feature/awesome-feature - -# Connect repository to global namespace -$ make link -``` - -## Coverage - -We try and make sure that each new feature or bug fix has tests to go along with them in order to keep code coverages consistent and increasing. We are actively striving for 100% code coverage! - -``` -# You can run the following command to find out coverage +```bash $ npm run test-coverage ``` -## Benchmarking - -We often want to know if the bug we've fixed for the feature we've added has any sort of performance impact. We've created a [benchmark suite](https://github.com/npm/benchmarks) to run against the CLI project from pull-requests. If you would like to know if there are any performance impacts to the work you're contributing, simply do the following: +## Performance & Benchmarks -1. Make a pull-request against this repository -2. Add the following comment to the pull-request: "`test this please ✅`" +We've set up an automated [benchmark](https://github.com/npm/benchmarks) integration that will run against all Pull Requests; Posting back a comment with the results of the run. -This will trigger the [benchmark suite](https://github.com/npm/benchmarks) to run against your pull-request, and when it's finished running it will post a comment on your pull-request just like below. You'll be able to see the results from the suite inline in your pull-request. - -> You'll notice that the bot-user will also add a 🚀 reaction to your comment to -let you know that it's sent the request to start the benchmark suite. +**Example:** ![image](https://user-images.githubusercontent.com/2818462/72312698-e2e57f80-3656-11ea-9fcf-4a8f6b97b0d1.png) -If you've updated your pull-request and you'd like to run the the benchmark suite again, simple update your original comment, by adding `test this please ✅` again, or simply just adding another emoji to the **end**. _(The trigger is the phrase "test this please ✅" at the beginning of a comment. Updates will trigger as well, so long as the phrase stays at the beginning.)_. - -![image](https://user-images.githubusercontent.com/2818462/72313006-ec231c00-3657-11ea-9bd9-227634d67362.png) - -## Types of Contributions - -### Contributing an Issue? - -Great!! Is your [new issue](https://github.com/npm/cli/issues/new/choose) a [bug](https://github.com/npm/cli/issues/new?template=bug.md&title=%5BBUG%5D+%3Ctitle%3E), a [feature](https://github.com/npm/cli/issues/new?template=feature.md&title=%5BFEATURE%5D+%3Ctitle%3E), or a [question](https://github.com/npm/cli/issues/new?template=question.md&title=%5BQUESTION%5D+%3Ctitle%3E)? - -### Contributing a Question? - -Huh? 🤔 Got a situation you're not sure about?! Perfect! We've got some resources you can use. - -* Our [documentation site](https://docs.npmjs.com/) -* The local docs that come with the CLI project - - > **Example**: `npm help install --viewer browser` - -* The man pages that are built and shipped with the CLI - - > **Example**: `man npm-install` (only on linux/macOS) - -* Search of the [current issues](https://github.com/npm/cli/issues) - -### Contributing a Bug Fix? - -We'd be happy to triage and help! Head over to the issues and [create a new one](https://github.com/npm/cli/issues/new?template=bug.md&title=%5BBUG%5D+%3Ctitle%3E)! - -> We'll need a little bit of information about what happened, rather than "it broke". Such as: -* When did/does this bug happen? -* Can you reproduce it? _(Can you make it happen more than once.)_ -* What version of `node`/`npm` are you running on your computer? -* What did you expect it to do? -* What did it _actually do? -* etc... - -### Contributing a Feature? - -Snazzy, we're always up for fancy new things! If the feature is fairly minor, the team can triage it and prioritize it into our backlog. However, if the feature is a little more complex, then it's best to create an [RFC](https://en.wikipedia.org/wiki/Request_for_Comments) in our [RFC repository](https://github.com/npm/rfcs). Exactly how to do that is outlined in that repository. If you're not sure _exactly_ how to implement your idea, or don't want to make a document about your idea, then please create an issue on that repository. We consider these RRFC's, or a "Requesting Request For Comment". - -## Development Dependencies - -You'll need a few things installed in order to update and test the CLI project during development: - -* [node](https://nodejs.org/) v8 or greater - -> We recommend that you have a [node version manager](https://github.com/nvm-sh/nvm) installed if you plan on fixing bugs that might be present in a specific version of node. With a version manager you can easily switch versions of node and test if your changes to the CLI project are working. - -* [git](https://git-scm.com/) v2.11+ - - -## Dependencies - -> Package vendoring is commonly referred to as the case where dependent packages are stored in the same place as your project. That usually means you dependencies are checked into your source management system, such as Git. +You can learn more about this tool, including how to run & configure it manually, [here](https://github.com/npm/benchmarks) -The CLI project vendors its dependencies in the `node_modules/` folder. Meaning all the dependencies that the CLI project uses are contained within the project itself. This is represented by the `bundledDependencies` section in the root level `package.json` file. The main reason for this is because the `npm` CLI project is distributed with the NodeJS runtime and needs to work out of the box, which means all dependencies need to be available after the runtime is installed. +## Reporting Bugs -There are a couple scripts created to help manage this process in the `scripts/` folder. +When submitting a new bug report, please first [search](https://github.com/npm/cli/issues) for an existing or similar report & then use one of our existing [issue templates](https://github.com/npm/cli/issues/new/choose) if you believe you've come across a unique problem. Duplicate issues, or issues that don't use one of our templates may get closed without a response. diff --git a/README.md b/README.md index 794a24b6b152..9350087f62cd 100644 --- a/README.md +++ b/README.md @@ -1,163 +1,53 @@ -npm(1) -- a JavaScript package manager -============================== +[![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/npm/cli/Node%20CI/latest)](https://github.com/npm/cli/actions?query=workflow%3A%22Node+CI%22+branch%3Alatest) [![Coveralls github branch](https://img.shields.io/coveralls/github/npm/cli/latest)](https://coveralls.io/github/npm/cli?branch=latest) -[![Build Status](https://img.shields.io/travis/npm/cli/latest.svg)](https://travis-ci.org/npm/cli) +# npm - a JavaScript package manager -## SYNOPSIS +### Requirements -This is just enough info to get you up and running. +* [**Node.js** `v10`](https://nodejs.org/en/download/) or higher must be installed to run this program -Much more info will be available via `npm help` once it's installed. +### Installation -## IMPORTANT +**`npm`** comes bundled with [**`node`**](https://nodejs.org/), & most third-party distributions, by default. Officially supported downloads/distributions can be found at: [nodejs.org/en/download](https://nodejs.org/en/download) -**You need node v6 or higher to run this program.** +#### Direct Download -To install an old **and unsupported** version of npm that works on node v5 -and prior, clone the git repo and dig through the old tags and branches. +You can download & install **`npm`** directly from [**npmjs**.com](https://npmjs.com/) using our custom `install.sh` script: -**npm is configured to use npm, Inc.'s public registry at - by default.** Use of the npm public registry -is subject to terms of use available at . - -You can configure npm to use any compatible registry you -like, and even run your own registry. Check out the [doc on -registries](https://docs.npmjs.com/misc/registry). - -## Super Easy Install - -npm is bundled with [node](https://nodejs.org/en/download/). - -### Windows Computers - -[Get the MSI](https://nodejs.org/en/download/). npm is in it. - -### Apple Macintosh Computers - -[Get the pkg](https://nodejs.org/en/download/). npm is in it. - -### Other Sorts of Unices - -Run `make install`. npm will be installed with node. - -If you want a more fancy pants install (a different version, customized -paths, etc.) then read on. - -## Fancy Install (Unix) - -There's a pretty robust install script at -. You can download that and run it. - -Here's an example using curl: - -```sh +```bash curl -L https://www.npmjs.com/install.sh | sh ``` -### Slightly Fancier +#### Node Version Managers -You can set any npm configuration params with that script: +If you're looking to manage multiple versions of **`node`** &/or **`npm`**, consider using a "Node Version Manager" such as: -```sh -npm_config_prefix=/some/path sh install.sh -``` +* [**`nvm`**](https://github.com/nvm-sh/nvm) +* [**`nvs`**](https://github.com/jasongin/nvs) +* [**`nave`**](https://github.com/isaacs/nave) +* [**`n`**](https://github.com/tj/n) +* [**`volta`**](https://github.com/volta-cli/volta) -Or, you can run it in uber-debuggery mode: +### Usage -```sh -npm_debug=1 sh install.sh +```bash +npm ``` -### Even Fancier - -Get the code with git. Use `make` to build the docs and do other stuff. -If you plan on hacking on npm, `make link` is your friend. - -If you've got the npm source code, you can also semi-permanently set -arbitrary config keys using the `./configure --key=val ...`, and then -run npm commands by doing `node bin/npm-cli.js `. (This is helpful -for testing, or running stuff without actually installing npm itself.) - -## Windows Install or Upgrade - -Many improvements for Windows users have been made in npm 3 - you will have a better -experience if you run a recent version of npm. To upgrade, either use [Microsoft's -upgrade tool](https://github.com/felixrieseberg/npm-windows-upgrade), -[download a new version of Node](https://nodejs.org/en/download/), -or follow the Windows upgrade instructions in the -[Installing/upgrading npm](https://npm.community/t/installing-upgrading-npm/251/2) post. - -If that's not fancy enough for you, then you can fetch the code with -git, and mess with it directly. - -## Installing on Cygwin - -No. - -## Uninstalling - -So sad to see you go. - -```sh -sudo npm uninstall npm -g -``` -Or, if that fails, - -```sh -sudo make uninstall -``` - -## More Severe Uninstalling - -Usually, the above instructions are sufficient. That will remove -npm, but leave behind anything you've installed. - -If you would like to remove all the packages that you have installed, -then you can use the `npm ls` command to find them, and then `npm rm` to -remove them. - -To remove cruft left behind by npm 0.x, you can use the included -`clean-old.sh` script file. You can run it conveniently like this: - -```sh -npm explore npm -g -- sh scripts/clean-old.sh -``` - -npm uses two configuration files, one for per-user configs, and another -for global (every-user) configs. You can view them by doing: - -```sh -npm config get userconfig # defaults to ~/.npmrc -npm config get globalconfig # defaults to /usr/local/etc/npmrc -``` - -Uninstalling npm does not remove configuration files by default. You -must remove them yourself manually if you want them gone. Note that -this means that future npm installs will not remember the settings that -you have chosen. - -## More Docs - -Check out the [docs](https://docs.npmjs.com/). - -You can use the `npm help` command to read any of them. - -If you're a developer, and you want to use npm to publish your program, -you should [read this](https://docs.npmjs.com/misc/developers). - -## BUGS - -When you find issues, please report them: - -* web: - -* archived web: - +### Links & Resources -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. +* [**Documentation**](https://docs.npmjs.com/) - Official docs & how-tos for all things **npm** + * Note: you can also search docs locally with `npm help-search ` +* [**Bug Tracker**](https://github.com/npm/cli/issues) - Search or submit bugs against the CLI +* [**Roadmap**](https://github.com/npm/roadmap) - Track & follow along with our public roadmap +* [**Feedback**](https://github.com/npm/feedback) - Contribute ideas & discussion around the npm registry, website & CLI +* [**RFCs**](https://github.com/npm/rfcs) - Contribute ideas & specifications for the API/design of the npm CLI +* [**Service Status**](https://status.npmjs.org/) - Monitor the current status & see incident reports for the website & registry +* [**Project Status**](https://npm.github.io/statusboard/) - See the health of all our maintained OSS projects in one view +* [**Events Calendar**](https://calendar.google.com/calendar/u/0/embed?src=npmjs.com_oonluqt8oftrt0vmgrfbg6q6go@group.calendar.google.com) - Keep track of our Open RFC calls, releases, meetups, conferences & more +* [**Support**](https://www.npmjs.com/support) - Experiencing problems with the **npm** [website](https://npmjs.com) or [registry](https://registry.npmjs.org)? File a ticket [here](https://www.npmjs.com/support) -## SEE ALSO +### Acknowledgments -* npm(1) -* npm-help(1) +* `npm` is configured to use the **npm Public Registry** at [https://registry.npmjs.org](https://registry.npmjs.org) by default; Usage of this registry is subject to **Terms of Use** available at [https://npmjs.com/policies/terms](https://npmjs.com/policies/terms) +* You can configure `npm` to use any other compatible registry you prefer. You can read more about configuring third-party registries [here](https://docs.npmjs.com/cli/v7/using-npm/registry) \ No newline at end of file diff --git a/docs/content/commands/npm-owner.md b/docs/content/commands/npm-owner.md index 6479f3bdd11f..69eba56afd97 100644 --- a/docs/content/commands/npm-owner.md +++ b/docs/content/commands/npm-owner.md @@ -39,4 +39,3 @@ on the command line when changing ownership with `--otp`. * [npm publish](/commands/npm-publish) * [npm registry](/using-npm/registry) * [npm adduser](/commands/npm-adduser) -* [npm disputes](/using-npm/disputes) diff --git a/docs/content/commands/npm-version.md b/docs/content/commands/npm-version.md index 5f93ef44ae5d..0eb814b9899b 100644 --- a/docs/content/commands/npm-version.md +++ b/docs/content/commands/npm-version.md @@ -83,37 +83,37 @@ Take the following example: } ``` -This runs all your tests, and proceeds only if they pass. Then runs your `build` script, and +This runs all your tests and proceeds only if they pass. Then runs your `build` script, and adds everything in the `dist` directory to the commit. After the commit, it pushes the new commit and tag up to the server, and deletes the `build/temp` directory. ### Configuration -#### allow-same-version +#### `allow-same-version` -* Default: false +* Default: `false` * Type: Boolean -Prevents throwing an error when `npm version` is used to set the new version +Prevents throwing an error when `npm version` is used to set the new version to the same value as the current version. -#### git-tag-version +#### `git-tag-version` -* Default: true +* Default: `true` * Type: Boolean Commit and tag the version change. -#### commit-hooks +#### `commit-hooks` -* Default: true +* Default: `true` * Type: Boolean Run git commit hooks when committing the version change. -#### sign-git-tag +#### `sign-git-tag` -* Default: false +* Default: `false` * Type: Boolean Pass the `-s` flag to git to sign the tag. @@ -126,5 +126,4 @@ Note that you must have a default GPG key set up in your git config for this to * [npm run-script](/commands/npm-run-script) * [npm scripts](/using-npm/scripts) * [package.json](/configuring-npm/package-json) -* [semver](/using-npm/semver) * [config](/using-npm/config) diff --git a/docs/content/commands/npm-view.md b/docs/content/commands/npm-view.md index 3404c0314335..bf09c2ba4f36 100644 --- a/docs/content/commands/npm-view.md +++ b/docs/content/commands/npm-view.md @@ -17,50 +17,48 @@ aliases: info, show, v This command shows data about a package and prints it to the stream referenced by the `outfd` config, which defaults to stdout. -To show the package registry entry for the `connect` package, you can do -this: +As an example, to view information about the `connect` package from the registry, you would run: ```bash npm view connect ``` -The default version is "latest" if unspecified. +The default version is `"latest"` if unspecified. Field names can be specified after the package descriptor. For example, to show the dependencies of the `ronn` package at version -0.3.5, you could do the following: +`0.3.5`, you could do the following: ```bash npm view ronn@0.3.5 dependencies ``` You can view child fields by separating them with a period. -To view the git repository URL for the latest version of npm, you could -do this: +To view the git repository URL for the latest version of `npm`, you would run the following command: ```bash npm view npm repository.url ``` This makes it easy to view information about a dependency with a bit of -shell scripting. For example, to view all the data about the version of -opts that ronn depends on, you can do this: +shell scripting. For example, to view all the data about the version of +`opts` that `ronn` depends on, you could write the following: ```bash npm view opts@$(npm view ronn dependencies.opts) ``` For fields that are arrays, requesting a non-numeric field will return -all of the values from the objects in the list. For example, to get all -the contributor names for the "express" project, you can do this: +all of the values from the objects in the list. For example, to get all +the contributor names for the `express` package, you would run: ```bash npm view express contributors.email ``` You may also use numeric indices in square braces to specifically select -an item in an array field. To just get the email address of the first -contributor in the list, you can do this: +an item in an array field. To just get the email address of the first +contributor in the list, you can run: ```bash npm view express contributors[0].email @@ -75,7 +73,7 @@ npm view express contributors.name contributors.email ``` "Person" fields are shown as a string if they would be shown as an -object. So, for example, this will show the list of npm contributors in +object. So, for example, this will show the list of `npm` contributors in the shortened string format. (See [`package.json`](/configuring-npm/package.json) for more on this.) ```bash @@ -83,12 +81,12 @@ npm view npm contributors ``` If a version range is provided, then data will be printed for every -matching version of the package. This will show which version of jsdom -was required by each matching version of yui3: +matching version of the package. This will show which version of `jsdom` +was required by each matching version of `yui3`: ```bash npm view yui3@'>0.5.4' dependencies.jsdom -``` +``` To show the `connect` package version history, you can do this: @@ -100,15 +98,15 @@ npm view connect versions ### Output If only a single string field for a single version is output, then it -will not be colorized or quoted, so as to enable piping the output to +will not be colorized or quoted, to enable piping the output to another command. If the field is an object, it will be output as a JavaScript object literal. -If the --json flag is given, the outputted fields will be JSON. +If the `--json` flag is given, the outputted fields will be JSON. -If the version range matches multiple versions, than each printed value +If the version range matches multiple versions then each printed value will be prefixed with the version it applies to. -If multiple fields are requested, than each of them are prefixed with +If multiple fields are requested, then each of them is prefixed with the field name. ### See Also diff --git a/docs/content/configuring-npm/package-json.md b/docs/content/configuring-npm/package-json.md index caa1e16a3267..4b3fd2ba9345 100644 --- a/docs/content/configuring-npm/package-json.md +++ b/docs/content/configuring-npm/package-json.md @@ -63,8 +63,6 @@ Version must be parseable by [node-semver](https://github.com/npm/node-semver), which is bundled with npm as a dependency. (`npm install semver` to use it yourself.) -More on version numbers and ranges at [semver](/using-npm/semver). - ### description Put a description in it. It's a string. This helps people discover your @@ -564,8 +562,8 @@ tarball or git URL. **Please do not put test harnesses or transpilers or other "development" time tools in your `dependencies` object.** See `devDependencies`, below. -See [semver](/using-npm/semver) for more details about specifying version -ranges. +See [semver]([/using-npm/semver](https://github.com/npm/node-semver#versions)) +for more details about specifying version ranges. * `version` Must match `version` exactly * `>version` Must be greater than `version` @@ -573,8 +571,8 @@ ranges. * `` -2. Email the author, CC -3. After a few weeks, if there's no resolution, we'll sort it out. - -Don't squat on package names. Publish code or move out of the way. - -### 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. Alice writes a JavaScript module `foo`, which is not node-specific. Alice - doesn't use node at all. Yusuf wants to use `foo` in node, so he wraps it in - an npm module. Some time later, Alice starts using node, and wants to take - over management of her program. -2. Yusuf writes an npm module `foo`, and publishes it. Perhaps much later, Alice - finds a bug in `foo`, and fixes it. She sends a pull request to Yusuf, but - Yusuf 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. Alice would like to publish a new `foo`, but can't, - because the name is taken. -3. Yusuf 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. Alice 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. Yusuf 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, Alice writes a much more complete `foo` parser, but can't publish, - because Yusuf's `foo` is in the way. - -1. `npm owner ls foo`. This will tell Alice the email address of the owner - (Yusuf). -2. Alice emails Yusuf, explaining the situation **as respectfully as possible**, - and what she would like to do with the module name. She adds the npm support - staff to the CC list of the email. Mention in the email - that Yusuf can run npm owner `add alice foo` to add Alice as an owner of the - foo package. -3. After a reasonable amount of time, if Yusuf has not responded, or if Yusuf - and Alice can't come to any sort of resolution, email support - and we'll sort it out. ("Reasonable" is usually at least - 4 weeks.) - -### 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 package 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. -4. "Squatting" on a package name that you plan to use, but aren't actually - using. Sorry, I don't care how great the name is, or how perfect a fit it is - for the thing that someday might happen. If someone wants to use it today, - and you're just taking up space with an empty tarball, you're going to be - evicted. -5. Putting empty packages in the registry. Packages must have SOME - functionality. It can be silly, but it can't be nothing. (See also: - squatting.) -6. Doing weird things with the registry, like using it as your own personal - application database or otherwise putting non-packagey things into it. -7. Other things forbidden by the npm - [Code of Conduct](https://www.npmjs.com/policies/conduct) such as hateful - language, pornographic content, or harassment. - -If you see bad behavior like this, please report it to right -away. **You are never expected to resolve abusive behavior on your own. We are -here to help.** - -### Trademarks - -If you think another npm publisher is infringing your trademark, such as by -using a confusingly similar package name, email with a link to -the package or user account on [https://www.npmjs.com/](https://www.npmjs.com/). -Attach a copy of your trademark registration certificate. - -If we see that the package's publisher is intentionally misleading others by -misusing your registered mark without permission, we will transfer the package -name to you. Otherwise, we will contact the package publisher and ask them to -clear up any confusion with changes to their package's `README` file or -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/cli/commits/latest/doc/misc/npm-disputes.md) -to view the changes. - -### License - -Copyright (C) npm, Inc., All rights reserved - -This document may be reused under a Creative Commons Attribution-ShareAlike -License. - -### See also - -* [npm registry](/using-npm/registry) -* [npm owner](/commands/npm-owner) diff --git a/docs/content/using-npm/registry.md b/docs/content/using-npm/registry.md index b7a18712f8be..c07fa7a48e88 100644 --- a/docs/content/using-npm/registry.md +++ b/docs/content/using-npm/registry.md @@ -10,7 +10,7 @@ To resolve packages by name and version, npm talks to a registry website that implements the CommonJS Package Registry specification for reading package info. -npm is configured to use npm, Inc.'s public registry at +npm is configured to use the **npm public registry** at by default. Use of the npm public registry is subject to terms of use available at . @@ -23,9 +23,7 @@ write APIs as well, to allow for publishing packages and managing user account information. The npm public registry is powered by a CouchDB database, -of which there is a public mirror at -. The code for the couchapp is -available at . +of which there is a public mirror at . The registry URL used is determined by the scope of the package (see [`scope`](/using-npm/scope). If no scope is specified, the default registry is used, which is @@ -55,44 +53,18 @@ about your environment: The npm registry does not try to correlate the information in these headers with any authenticated accounts that may be used in the same requests. -### Can I run my own private registry? +### How can I prevent my package from being published in the official registry? -Yes! - -The easiest way is to replicate the couch database, and use the same (or -similar) design doc to implement the APIs. - -If you set up continuous replication from the official CouchDB, and then -set your internal CouchDB as the registry config, then you'll be able -to read any published packages, in addition to your private ones, and by -default will only publish internally. - -If you then want to publish a package for the whole world to see, you can -simply override the `--registry` option for that `publish` command. - -### I don't want my package published in the official registry. It's private. - -Set `"private": true` in your package.json to prevent it from being +Set `"private": true` in your `package.json` to prevent it from being published at all, or `"publishConfig":{"registry":"http://my-internal-registry.local"}` -to force it to be published only to your internal registry. +to force it to be published only to your internal/private registry. See [`package.json`](/configuring-npm/package-json) for more info on what goes in the package.json file. -### Will you replicate from my registry into the public one? - -No. If you want things to be public, then publish them into the public -registry using npm. What little security there is would be for nought -otherwise. - -### Do I have to use couchdb to build a registry that npm can talk to? - -No, but it's way easier. Basically, yes, you do, or you have to -effectively implement the entire CouchDB API anyway. - -### Is there a website or something to see package docs and such? +### Where can I find my own, & other's, published packages? -Yes, head over to + ### See also @@ -100,4 +72,3 @@ Yes, head over to * [config](/using-npm/config) * [npmrc](/configuring-npm/npmrc) * [npm developers](/using-npm/developers) -* [npm disputes](/using-npm/disputes) diff --git a/docs/content/using-npm/removal.md b/docs/content/using-npm/removal.md index 7b35460b595e..c5e13b6741b6 100644 --- a/docs/content/using-npm/removal.md +++ b/docs/content/using-npm/removal.md @@ -58,8 +58,6 @@ modules. To track those down, you can do the following: find /usr/local/{lib/node,bin} -exec grep -l npm \{\} \; ; ``` -(This is also in the README file.) - ### See also * [npm uninstall](/commands/npm-uninstall) diff --git a/docs/content/using-npm/semver.md b/docs/content/using-npm/semver.md deleted file mode 100644 index 55141ed537c5..000000000000 --- a/docs/content/using-npm/semver.md +++ /dev/null @@ -1,415 +0,0 @@ ---- -title: semver -section: 7 -description: The semantic versioner for npm ---- - -## Install - -```bash -npm install --save semver -```` - -## Usage - -As a node module: - -```js -const semver = require('semver') - -semver.valid('1.2.3') // '1.2.3' -semver.valid('a.b.c') // null -semver.clean(' =v1.2.3 ') // '1.2.3' -semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true -semver.gt('1.2.3', '9.8.7') // false -semver.lt('1.2.3', '9.8.7') // true -semver.minVersion('>=1.0.0') // '1.0.0' -semver.valid(semver.coerce('v2')) // '2.0.0' -semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7' -``` - -As a command-line utility: - -``` -$ semver -h - -A JavaScript implementation of the https://semver.org/ specification -Copyright Isaac Z. Schlueter - -Usage: semver [options] [ [...]] -Prints valid versions sorted by SemVer precedence - -Options: --r --range - Print versions that match the specified range. - --i --increment [] - Increment a version by the specified level. Level can - be one of: major, minor, patch, premajor, preminor, - prepatch, or prerelease. Default level is 'patch'. - Only one version may be specified. - ---preid - Identifier to be used to prefix premajor, preminor, - prepatch or prerelease version increments. - --l --loose - Interpret versions and ranges loosely - --p --include-prerelease - Always include prerelease versions in range matching - --c --coerce - Coerce a string into SemVer if possible - (does not imply --loose) - -Program exits successfully if any valid version satisfies -all supplied ranges, and prints all satisfying versions. - -If no satisfying versions are found, then exits failure. - -Versions are printed in ascending order, so supplying -multiple versions to the utility will just sort them. -``` - -## Versions - -A "version" is described by the `v2.0.0` specification found at -. - -A leading `"="` or `"v"` character is stripped off and ignored. - -## Ranges - -A `version range` is a set of `comparators` which specify versions -that satisfy the range. - -A `comparator` is composed of an `operator` and a `version`. The set -of primitive `operators` is: - -* `<` Less than -* `<=` Less than or equal to -* `>` Greater than -* `>=` Greater than or equal to -* `=` Equal. If no operator is specified, then equality is assumed, - so this operator is optional, but MAY be included. - -For example, the comparator `>=1.2.7` would match the versions -`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6` -or `1.1.0`. - -Comparators can be joined by whitespace to form a `comparator set`, -which is satisfied by the **intersection** of all of the comparators -it includes. - -A range is composed of one or more comparator sets, joined by `||`. A -version matches a range if and only if every comparator in at least -one of the `||`-separated comparator sets is satisfied by the version. - -For example, the range `>=1.2.7 <1.3.0` would match the versions -`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`, -or `1.1.0`. - -The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`, -`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`. - -### Prerelease Tags - -If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then -it will only be allowed to satisfy comparator sets if at least one -comparator with the same `[major, minor, patch]` tuple also has a -prerelease tag. - -For example, the range `>1.2.3-alpha.3` would be allowed to match the -version `1.2.3-alpha.7`, but it would *not* be satisfied by -`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater -than" `1.2.3-alpha.3` according to the SemVer sort rules. The version -range only accepts prerelease tags on the `1.2.3` version. The -version `3.4.5` *would* satisfy the range, because it does not have a -prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`. - -The purpose for this behavior is twofold. First, prerelease versions -frequently are updated very quickly, and contain many breaking changes -that are (by the author's design) not yet fit for public consumption. -Therefore, by default, they are excluded from range matching -semantics. - -Second, a user who has opted into using a prerelease version has -clearly indicated the intent to use *that specific* set of -alpha/beta/rc versions. By including a prerelease tag in the range, -the user is indicating that they are aware of the risk. However, it -is still not appropriate to assume that they have opted into taking a -similar risk on the *next* set of prerelease versions. - -Note that this behavior can be suppressed (treating all prerelease -versions as if they were normal versions, for the purpose of range -matching) by setting the `includePrerelease` flag on the options -object to any -[functions](https://github.com/npm/node-semver#functions) that do -range matching. - -#### Prerelease Identifiers - -The method `.inc` takes an additional `identifier` string argument that -will append the value of the string as a prerelease identifier: - -```javascript -semver.inc('1.2.3', 'prerelease', 'beta') -// '1.2.4-beta.0' -``` - -command-line example: - -```bash -$ semver 1.2.3 -i prerelease --preid beta -1.2.4-beta.0 -``` - -Which then can be used to increment further: - -```bash -$ semver 1.2.4-beta.0 -i prerelease -1.2.4-beta.1 -``` - -### Advanced Range Syntax - -Advanced range syntax desugars to primitive comparators in -deterministic ways. - -Advanced ranges may be combined in the same way as primitive -comparators using white space or `||`. - -#### Hyphen Ranges `X.Y.Z - A.B.C` - -Specifies an inclusive set. - -* `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4` - -If a partial version is provided as the first version in the inclusive -range, then the missing pieces are replaced with zeroes. - -* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4` - -If a partial version is provided as the second version in the -inclusive range, then all versions that start with the supplied parts -of the tuple are accepted, but nothing that would be greater than the -provided tuple parts. - -* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0` -* `1.2.3 - 2` := `>=1.2.3 <3.0.0` - -#### X-Ranges `1.2.x` `1.X` `1.2.*` `*` - -Any of `X`, `x`, or `*` may be used to "stand in" for one of the -numeric values in the `[major, minor, patch]` tuple. - -* `*` := `>=0.0.0` (Any version satisfies) -* `1.x` := `>=1.0.0 <2.0.0` (Matching major version) -* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions) - -A partial version range is treated as an X-Range, so the special -character is in fact optional. - -* `""` (empty string) := `*` := `>=0.0.0` -* `1` := `1.x.x` := `>=1.0.0 <2.0.0` -* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0` - -#### Tilde Ranges `~1.2.3` `~1.2` `~1` - -Allows patch-level changes if a minor version is specified on the -comparator. Allows minor-level changes if not. - -* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0` -* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`) -* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`) -* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0` -* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`) -* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`) -* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in - the `1.2.3` version will be allowed, if they are greater than or - equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but - `1.2.4-beta.2` would not, because it is a prerelease of a - different `[major, minor, patch]` tuple. - -#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4` - -Allows changes that do not modify the left-most non-zero digit in the -`[major, minor, patch]` tuple. In other words, this allows patch and -minor updates for versions `1.0.0` and above, patch updates for -versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`. - -Many authors treat a `0.x` version as if the `x` were the major -"breaking-change" indicator. - -Caret ranges are ideal when an author may make breaking changes -between `0.2.4` and `0.3.0` releases, which is a common practice. -However, it presumes that there will *not* be breaking changes between -`0.2.4` and `0.2.5`. It allows for changes that are presumed to be -additive (but non-breaking), according to commonly observed practices. - -* `^1.2.3` := `>=1.2.3 <2.0.0` -* `^0.2.3` := `>=0.2.3 <0.3.0` -* `^0.0.3` := `>=0.0.3 <0.0.4` -* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in - the `1.2.3` version will be allowed, if they are greater than or - equal to `beta.2`. So, `1.2.3-beta.4` would be allowed, but - `1.2.4-beta.2` would not, because it is a prerelease of a - different `[major, minor, patch]` tuple. -* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4` Note that prereleases in the - `0.0.3` version *only* will be allowed, if they are greater than or - equal to `beta`. So, `0.0.3-pr.2` would be allowed. - -When parsing caret ranges, a missing `patch` value desugars to the -number `0`, but will allow flexibility within that value, even if the -major and minor versions are both `0`. - -* `^1.2.x` := `>=1.2.0 <2.0.0` -* `^0.0.x` := `>=0.0.0 <0.1.0` -* `^0.0` := `>=0.0.0 <0.1.0` - -A missing `minor` and `patch` values will desugar to zero, but also -allow flexibility within those values, even if the major version is -zero. - -* `^1.x` := `>=1.0.0 <2.0.0` -* `^0.x` := `>=0.0.0 <1.0.0` - -### Range Grammar - -Putting all this together, here is a Backus-Naur grammar for ranges, -for the benefit of parser authors: - -```bnf -range-set ::= range ( logical-or range ) * -logical-or ::= ( ' ' ) * '||' ( ' ' ) * -range ::= hyphen | simple ( ' ' simple ) * | '' -hyphen ::= partial ' - ' partial -simple ::= primitive | partial | tilde | caret -primitive ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial -partial ::= xr ( '.' xr ( '.' xr qualifier ? )? )? -xr ::= 'x' | 'X' | '*' | nr -nr ::= '0' | ['1'-'9'] ( ['0'-'9'] ) * -tilde ::= '~' partial -caret ::= '^' partial -qualifier ::= ( '-' pre )? ( '+' build )? -pre ::= parts -build ::= parts -parts ::= part ( '.' part ) * -part ::= nr | [-0-9A-Za-z]+ -``` - -## Functions - -All methods and classes take a final `options` object argument. All -options in this object are `false` by default. The options supported -are: - -- `loose` Be more forgiving about not-quite-valid semver strings. - (Any resulting output will always be 100% strict compliant, of - course.) For backwards compatibility reasons, if the `options` - argument is a boolean value instead of an object, it is interpreted - to be the `loose` param. -- `includePrerelease` Set to suppress the [default - behavior](https://github.com/npm/node-semver#prerelease-tags) of - excluding prerelease tagged versions from ranges unless they are - explicitly opted into. - -Strict-mode Comparators and Ranges will be strict about the SemVer -strings that they parse. - -* `valid(v)`: Return the parsed version, or null if it's not valid. -* `inc(v, release)`: Return the version incremented by the release - type (`major`, `premajor`, `minor`, `preminor`, `patch`, - `prepatch`, or `prerelease`), or null if it's not valid - * `premajor` in one call will bump the version up to the next major - version and down to a prerelease of that major version. - `preminor`, and `prepatch` work the same way. - * If called from a non-prerelease version, the `prerelease` will work the - same as `prepatch`. It increments the patch version, then makes a - prerelease. If the input version is already a prerelease it simply - increments it. -* `prerelease(v)`: Returns an array of prerelease components, or null - if none exist. Example: `prerelease('1.2.3-alpha.1') -> ['alpha', 1]` -* `major(v)`: Return the major version number. -* `minor(v)`: Return the minor version number. -* `patch(v)`: Return the patch version number. -* `intersects(r1, r2, loose)`: Return true if the two supplied ranges - or comparators intersect. -* `parse(v)`: Attempt to parse a string as a semantic version, returning either - a `SemVer` object or `null`. - -### Comparison - -* `gt(v1, v2)`: `v1 > v2` -* `gte(v1, v2)`: `v1 >= v2` -* `lt(v1, v2)`: `v1 < v2` -* `lte(v1, v2)`: `v1 <= v2` -* `eq(v1, v2)`: `v1 == v2` This is true if they're logically equivalent, - even if they're not the exact same string. You already know how to - compare strings. -* `neq(v1, v2)`: `v1 != v2` The opposite of `eq`. -* `cmp(v1, comparator, v2)`: Pass in a comparison string, and it'll call - the corresponding function above. `"==="` and `"!=="` do simple - string comparison, but are included for completeness. Throws if an - invalid comparison string is provided. -* `compare(v1, v2)`: Return `0` if `v1 == v2`, or `1` if `v1` is greater, or `-1` if - `v2` is greater. Sorts in ascending order if passed to `Array.sort()`. -* `rcompare(v1, v2)`: The reverse of compare. Sorts an array of versions - in descending order when passed to `Array.sort()`. -* `diff(v1, v2)`: Returns difference between two versions by the release type - (`major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, or `prerelease`), - or null if the versions are the same. - -### Comparators - -* `intersects(comparator)`: Return true if the comparators intersect - -### Ranges - -* `validRange(range)`: Return the valid range or null if it's not valid -* `satisfies(version, range)`: Return true if the version satisfies the - range. -* `maxSatisfying(versions, range)`: Return the highest version in the list - that satisfies the range, or `null` if none of them do. -* `minSatisfying(versions, range)`: Return the lowest version in the list - that satisfies the range, or `null` if none of them do. -* `minVersion(range)`: Return the lowest version that can possibly match - the given range. -* `gtr(version, range)`: Return `true` if version is greater than all the - versions possible in the range. -* `ltr(version, range)`: Return `true` if version is less than all the - versions possible in the range. -* `outside(version, range, hilo)`: Return true if the version is outside - the bounds of the range in either the high or low direction. The - `hilo` argument must be either the string `'>'` or `'<'`. (This is - the function called by `gtr` and `ltr`.) -* `intersects(range)`: Return true if any of the ranges comparators intersect - -Note that, since ranges may be non-contiguous, a version might not be -greater than a range, less than a range, *or* satisfy a range! For -example, the range `1.2 <1.2.9 || >2.0.0` would have a hole from `1.2.9` -until `2.0.0`, so the version `1.2.10` would not be greater than the -range (because `2.0.1` satisfies, which is higher), nor less than the -range (since `1.2.8` satisfies, which is lower), and it also does not -satisfy the range. - -If you want to know if a version satisfies or does not satisfy a -range, use the `satisfies(version, range)` function. - -### Coercion - -* `coerce(version)`: Coerces a string to semver if possible - -This aims to provide a very forgiving translation of a non-semver string to -semver. It looks for the first digit in a string, and consumes all -remaining characters which satisfy at least a partial semver (e.g., `1`, -`1.2`, `1.2.3`) up to the max permitted length (256 characters). Longer -versions are simply truncated (`4.6.3.9.2-alpha2` becomes `4.6.3`). All -surrounding text is simply ignored (`v3.4 replaces v3.3.1` becomes -`3.4.0`). Only text which lacks digits will fail coercion (`version one` -is not valid). The maximum length for any semver component considered for -coercion is 16 characters; longer components will be ignored -(`10000000000000000.4.7.4` becomes `4.7.4`). The maximum value for any -semver component is `Number.MAX_SAFE_INTEGER || (2**53 - 1)`; higher value -components are invalid (`9999999999999999.4.7.4` is likely invalid).