From f9248c0be63fba37a30098dc9215c752474380e3 Mon Sep 17 00:00:00 2001
From: Amal Hussein <amal@npmjs.com>
Date: Mon, 27 Jan 2020 17:37:28 -0500
Subject: [PATCH] chore(docs): update unpublish docs with both commands,
 removing policy info from cli docs, and added reference to unpublish policy
 docs Co-Authored-By: Michael 'afrolion' Perrotte <mike@npmjs.com>

PR-URL: https://github.com/npm/cli/pull/730
Credit: @nomadtechie
Close: #730
Reviewed-by: @darcyclarke
---
 docs/content/cli-commands/npm-unpublish.md | 26 +++++++++-------------
 lib/unpublish.js                           |  8 +++++--
 2 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/docs/content/cli-commands/npm-unpublish.md b/docs/content/cli-commands/npm-unpublish.md
index 5348023d9a840..c40f480a8bcb8 100644
--- a/docs/content/cli-commands/npm-unpublish.md
+++ b/docs/content/cli-commands/npm-unpublish.md
@@ -10,19 +10,21 @@ description: Remove a package from the registry
 
 ### Synopsis
 
+#### Unpublishing a single version of a package
+
 ```bash
-npm unpublish [<@scope>/]<pkg>[@<version>]
+npm unpublish [<@scope>/]<pkg>@<version>
 ```
 
-### Warning
+#### Unpublishing an entire package
 
-**It is generally considered bad behavior to remove versions of a library
-that others are depending on!**
+```bash
+npm unpublish [<@scope>/]<pkg> --force
+```
 
-Consider using the `deprecate` command
-instead, if your intent is to encourage users to upgrade.
+### Warning
 
-There is plenty of room on the registry.
+Consider using the `deprecate` command instead, if your intent is to encourage users to upgrade, or if you no longer want to maintain a package.
 
 ### Description
 
@@ -34,16 +36,10 @@ the root package entry is removed from the registry entirely.
 
 Even if a package version is unpublished, that specific name and
 version combination can never be reused. In order to publish the
-package again, a new version number must be used. Additionally,
-new versions of packages with every version unpublished may not
-be republished until 24 hours have passed.
+package again, a new version number must be used. If you unpublish the entire package, you may not publish any new versions of that package until 24 hours have passed.
 
-With the default registry (`registry.npmjs.org`), unpublish is
-only allowed with versions published in the last 72 hours. If you
-are trying to unpublish a version published longer ago than that,
-contact support@npmjs.com.
+To learn more about how unpublish is treated on the npm registry, see our <a href="https://www.npmjs.com/policies/unpublish" target="_blank" rel="noopener noreferrer"> unpublish policies</a>. 
 
-The scope is optional and follows the usual rules for [`scope`](/using-npm/scope).
 
 ### See Also
 
diff --git a/lib/unpublish.js b/lib/unpublish.js
index 203c8b592f109..59d7d1b5887d2 100644
--- a/lib/unpublish.js
+++ b/lib/unpublish.js
@@ -20,7 +20,11 @@ const readJson = BB.promisify(require('read-package-json'))
 const usage = require('./utils/usage.js')
 const whoami = BB.promisify(require('./whoami.js'))
 
-unpublish.usage = usage('npm unpublish [<@scope>/]<pkg>[@<version>]')
+unpublish.usage = usage(
+  'unpublish',
+  '\nnpm unpublish [<@scope>/]<pkg>@<version>' +
+    '\nnpm unpublish [<@scope>/]<pkg> --force'
+)
 
 function UsageError () {
   throw Object.assign(new Error(`Usage: ${unpublish.usage}`), {
@@ -75,7 +79,7 @@ function unpublish (args, cb) {
         'Refusing to delete entire project.\n' +
         'Run with --force to do this.\n' +
         unpublish.usage
-      ), {code: 'EUSAGE'})
+      ), { code: 'EUSAGE' })
     }
     if (!spec || path.resolve(spec.name) === npm.localPrefix) {
       // if there's a package.json in the current folder, then