Merge branch 'docs/npm-packages-refactor' into 'master'

Refactor the Packages documentation

See merge request gitlab-org/gitlab-ee!9095

doc/administration/index.md

@@ -126,8 +126,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Default labels](../user/admin_area/labels.html): Create labels that will be automatically added to every new project.
 - [Restrict the use of public or internal projects](../public_access/public_access.md#restricting-the-use-of-public-or-internal-projects): Restrict the use of visibility levels for users when they create a project or a snippet.
 - [Custom project templates](../user/admin_area/custom_project_templates.md): Configure a set of projects to be used as custom templates when creating a new project. **[PREMIUM ONLY]**
-- [Maven Repository](maven_repository.md): Enable Maven Repository within GitLab. **[PREMIUM ONLY]**
-- [NPM Registry](npm_registry.md): Enable NPM Registry within GitLab. **[PREMIUM ONLY]**
+- [Packages](packages.md): Enable GitLab to act as a Maven repository or NPM registry. **[PREMIUM ONLY]**
 
 ### Repository settings
 

doc/administration/maven_packages.md

-This document was moved to [another location](maven_repository.md).
+This document was moved to [another location](packages.md).

doc/administration/maven_repository.md

-# GitLab Maven Repository administration **[PREMIUM ONLY]**
-
->
-[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811)
-in GitLab 11.3. To learn how to use
-
-When the GitLab Maven Repository is enabled, every project in GitLab will have
-its own space to store [Maven](https://maven.apache.org/) packages.
-
-To learn how to use it, see the [user documentation](../user/project/packages/maven_repository.md).
-
-## Enabling the Maven Repository
-
-NOTE: **Note:**
-Once enabled, newly created projects will have the Packages feature enabled by
-default. Existing projects will need to
-[explicitly enabled it](../user/project/packages/maven_repository.md#enabling-the-packages-repository).
-
-To enable the Maven repository you need to enable [Packages feature](packages.md)
+This document was moved to [another location](packages.md).

doc/administration/npm_registry.md

-# GitLab NPM Registry administration **[PREMIUM ONLY]**
-
->
-[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934)
-in GitLab 11.7. To learn how to use
-
-When the GitLab NPM Registry is enabled, every project in GitLab will have
-its own space to store [NPM](https://www.npmjs.com/) packages.
-
-To learn how to use it, see the [user documentation](../user/project/packages/npm_registry.md).
-
-## Enabling the NPM Registry
-
-NOTE: **Note:**
-Once enabled, newly created projects will have the Packages feature enabled by
-default. Existing projects will need to
-[explicitly enabled it](../user/project/packages/npm_registry.md#enabling-the-packages-repository).
-
-To enable the NPM Registry you need to enable [Packages feature](packages.md)
+This document was moved to [another location](packages.md).

doc/administration/packages.md

 # GitLab Packages administration **[PREMIUM ONLY]**
 
-Package feature provides a support for next products:
+GitLab Packages allows organizations to utilize GitLab as a private repository
+for a variety of common package managers. Users are able to build and publish
+packages, which can be easily consumed as a dependency in downstream projects.
 
-* [Maven Repository](maven_repository.md)
-* [NPM Registry](npm_registry.md)
+The Packages feature allows GitLab to act as a repository for the following:
+
+| Software repository | Description | Available in GitLab version |
+| ------------------- | ----------- | --------------------------- |
+| [Maven Repository](../user/project/packages/maven_repository.md) | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ |
+| [NPM Registry](../user/project/packages/npm_registry.md)   | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ |
 
 ## Enabling the Packages feature
 
+NOTE: **Note:**
+After the Packages feature is enabled, the repositories are available for
+for all new projects by default. To enable it for existing projects, users will
+have to explicitly do so in the project's settings.
+
 To enable the Packages feature:
 
 **Omnibus GitLab installations**

doc/user/project/packages/maven_repository.md

 # GitLab Maven Repository **[PREMIUM]**
 
-> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5811) in
+  [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
 
 With the GitLab [Maven](https://maven.apache.org) Repository, every
 project can have its own space to store its Maven artifacts.
 
 ![GitLab Maven Repository](img/maven_package_view.png)
 
-## Enabling Maven Repository
+## Enabling the Maven Repository
 
 NOTE: **Note:**
 This option is available only if your GitLab administrator has
-[enabled Maven Repository](../../../administration/maven_repository.md).
+[enabled support for the Maven repository](../../../administration/packages.md).
 
-In order to use the GitLab Maven Repository, you must enable the
-Repository. To enable (or disable) it:
+After the Packages feature is enabled, the Maven Repository will be available for
+all new projects by default. To enable it for existing projects, or if you want
+to disable it:
 
 1. Navigate to your project's **Settings > General > Permissions**.
-1. Find the "Packages" feature and enable it.
+1. Find the Packages feature and enable or disable it.
 1. Click on **Save changes** for the changes to take effect.
 
 You should then be able to see the **Packages** section on the left sidebar.

doc/user/project/packages/npm_registry.md

 # GitLab NPM Registry **[PREMIUM]**
 
-> Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5934)
+  in [GitLab Premium](https://about.gitlab.com/pricing/) 11.7.
 
 With the GitLab NPM Registry, every
 project can have its own space to store NPM packages.
@@ -10,75 +11,95 @@ project can have its own space to store NPM packages.
 NOTE: **Note:**
 Only [scoped](https://docs.npmjs.com/misc/scope) packages are supported.
 
-## Enabling NPM Registry
+## Enabling the NPM Registry
 
 NOTE: **Note:**
 This option is available only if your GitLab administrator has
-[enabled Packages feature](../../../administration/npm_registry.md).
+[enabled support for the NPM registry](../../../administration/packages.md).
 
-In order to use the GitLab NPM Registry, you must enable the Packages feature.
-To enable (or disable) it:
+After the NPM registry is enabled, it will be available for all new projects
+by default. To enable it for existing projects, or if you want to disable it:
 
 1. Navigate to your project's **Settings > General > Permissions**.
-1. Find the "Packages" feature and enable it.
+1. Find the Packages feature and enable or disable it.
 1. Click on **Save changes** for the changes to take effect.
 
 You should then be able to see the **Packages** section on the left sidebar.
-Next, you must configure your project to authorize with the GitLab NPM
-registry.
+
+Before proceeding to authenticating with the GitLab NPM Registry, you should
+get familiar with the package naming convention.
 
 ## Package naming convention
 
-Note that **only packages that have the same path as the project** are supported.
+**Only packages that have the same path as the project** are supported. For
+ example:
 
 | Project                | Package                 | Supported |
-| ------- | ------- | --------------------------------- |
+| ---------------------- | ----------------------- | --------- |
 | `foo/bar`              | `@foo/bar`              | Yes       |
-| `gitlab-org/gitlab-ce` | `@foo/bar`              | No  |
 | `gitlab-org/gitlab-ce` | `@gitlab-org/gitlab-ce` | Yes       |
+| `gitlab-org/gitlab-ce` | `@foo/bar`              | No        |
+
+Now, you can configure your project to authenticate with the GitLab NPM
+Registry.
 
 ## Authenticating to the GitLab NPM Registry
 
-If a project is private or you want to upload NPM package to GitLab,
-credentials will need to be provided for authentication. Support is available for
-[oauth tokens](#authenticating-with-an-oauth-token) only.
+If a project is private or you want to upload an NPM package to GitLab,
+credentials will need to be provided for authentication. Support is available
+only for [OAuth tokens](../../../api/oauth2.md#resource-owner-password-credentials-flow).
+
+CAUTION: **2FA not supported:**
+Authentication for personal access tokens is not yet supported
+([#9140](https://gitlab.com/gitlab-org/gitlab-ee/issues/9140)). If you have 2FA
+enabled, you won't be able to authenticate to the GitLab NPM Registry.
 
-### Authenticating with an oauth token
+### Authenticating with an OAuth token
 
-To authenticate with a [oauth token](../../../api/oauth2.md),
+To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow),
 add a corresponding section to your `.npmrc` file:
 
-```
+```ini
 ; Set URL for your scoped packages.
 ; For example package with name `@foo/bar` will use this URL for download
 @foo:registry=https://gitlab.com/api/v4/packages/npm/
 
-; Add OAuth token for scoped packages URL. This will allow you to download
+; Add the OAuth token for the scoped packages URL. This will allow you to download
 ; `@foo/` packages from private projects.
-//localhost:3001/api/v4/packages/npm/:_authToken=1da4f6691c92a543f7416b8fe013357fda23b0730466841311b89809a51349ce
+//gitlab.com/api/v4/packages/npm/:_authToken=<your_oauth_token>
 
-; Add OAuth token for uploading to the registry. Replace `YOUR_PROJECT_ID`
-; with a project you want your package uploaded to. 
-//gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/:_authToken=YOUR_OAUTH_TOKEN
+; Add OAuth token for uploading to the registry. Replace <your_project_id>
+; with the project you want your package to be uploaded to.
+//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_oauth_token>
 ```
 
+Replace `<your_project_id>` with your project ID which can be found on the home page
+of your project and `<your_oauth_token>` with your OAuth token.
+
+If you have a self-hosted GitLab installation, replace `gitlab.com` with your
+domain name.
+
 You should now be able to download and upload NPM packages to your project.
 
 ## Uploading packages
 
-Before you will be able to upload a package, you need to specify registry for NPM. 
-To do this, you need to add next section to the bottom of `package.json`: 
+Before you will be able to upload a package, you need to specify the registry
+for NPM. To do this, add the following section to the bottom of `package.json`:
 
 ```json
   "publishConfig": {
-    "@foo:registry":"https://gitlab.com/api/v4/projects/YOUR_PROJECT_ID/packages/npm/"
+    "@foo:registry":"https://gitlab.com/api/v4/projects/<your_project_id>/packages/npm/"
   }
 ```
-Replace `YOUR_PROJECT_ID` with a project you want your package uploaded to. 
-And replace `@foo` with your own scope.
 
-Once you did it and have set up the [authorization](#authorizing-with-the-gitlab-npm-registry),
-test to upload an NPM package from a project of yours:
+Replace `<your_project_id>` with your project ID, which can be found on the home
+page of your project, and replace `@foo` with your own scope.
+
+If you have a self-hosted GitLab installation, replace `gitlab.com` with your
+domain name.
+
+Once you have enabled it and set up [authentication](#authenticating-to-the-gitlab-npm-registry),
+you can upload an NPM package to your project:
 
 ```sh
 npm publish
@@ -90,5 +111,5 @@ packages or even delete them.
 ## Uploading a package with the same version twice
 
 If you upload a package with a same name and version twice, GitLab will show
-both packages in UI. But API will expose only one package per version for `npm install`
-and it will be the most recent one.
+both packages in the UI, but the GitLab NPM Registry will expose the most recent
+one as it supports only one package per version for `npm install`.