Merge branch 'selhorn-maven-repo-1' into 'master'

Docs: Updated Maven Repository topic

See merge request gitlab-org/gitlab!44529

doc/api/README.md

@@ -163,7 +163,7 @@ to authenticate with the API:
   - [Conan Repository](../user/packages/conan_repository/index.md)
   - [Container Registry](../user/packages/container_registry/index.md) (`$CI_REGISTRY_PASSWORD` is actually `$CI_JOB_TOKEN`, but this may change in the future)
   - [Go Proxy](../user/packages/go_proxy/index.md)
-  - [Maven Repository](../user/packages/maven_repository/index.md#authenticating-with-a-ci-job-token)
+  - [Maven Repository](../user/packages/maven_repository/index.md#authenticate-with-a-ci-job-token)
   - [NPM Repository](../user/packages/npm_registry/index.md#authenticating-with-a-ci-job-token)
   - [Nuget Repository](../user/packages/nuget_repository/index.md)
   - [PyPI Repository](../user/packages/pypi_repository/index.md#using-gitlab-ci-with-pypi-packages)

doc/user/packages/maven_repository/index.md

@@ -4,44 +4,24 @@ group: Package
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
-# GitLab Maven Repository
+# Maven packages in the Package Repository
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/5811) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/221259) to GitLab Core in 13.3.
 
-With the GitLab [Maven](https://maven.apache.org) Repository, every
-project can have its own space to store its Maven artifacts.
+Publish [Maven](https://maven.apache.org) artifacts in your project’s Package Registry.
+Then, install the packages whenever you need to use them as a dependency.
 
-![GitLab Maven Repository](img/maven_package_view_v12_6.png)
+## Build a Maven package
 
-## Enabling the Maven Repository
+This section explains how to install Maven and build a package.
 
-NOTE: **Note:**
-This option is available only if your GitLab administrator has
-[enabled support for the Maven repository](../../../administration/packages/index.md).
-
-After the Packages feature is enabled, the Maven Repository is 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 > Visibility, project features, permissions**.
-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 & Registries** section on the left sidebar.
-Next, you must configure your project to authorize with the GitLab Maven
-repository.
+If you already use Maven and know how to build your own packages, go to the
+[next section](#add-the-package-registry-as-a-maven-remote).
 
-## Getting Started with Maven
+Maven repositories work well with Gradle, too. To set up a Gradle project, see [get started with Gradle](#use-gradle-to-create-a-java-project).
 
-This section covers installing Maven and building a package. This is a
-quickstart to help if you're new to building Maven packages. If you're already
-using Maven and understand how to build your own packages, move onto the
-[next section](#adding-the-gitlab-package-registry-as-a-maven-remote).
-
-Maven repositories work well with Gradle, too. Move onto [getting started with Gradle](#getting-started-with-gradle) if you want to setup a Gradle project.
-
-### Installing Maven
+### Install Maven
 
 The required minimum versions are:
 
@@ -66,7 +46,7 @@ Default locale: en_GB, platform encoding: UTF-8
 OS name: "mac os x", version: "10.15.2", arch: "x86_64", family: "mac"
 ```
 
-### Creating a project
+### Create a project
 
 Understanding how to create a full Java project is outside the scope of this
 guide but you can follow the steps below to create a new project that can be
@@ -105,14 +85,14 @@ your project has been set up successfully:
 You should see a new directory where you ran this command matching your
 `DartifactId` parameter (in this case it should be `my-project`).
 
-## Getting started with Gradle
+## Use Gradle to create a Java project
+
+This section explains how to install Gradle and initialize a Java project.
 
-This section covers installing Gradle and initializing a Java project. This is a
-quickstart to help if you're new to Gradle. If you're already
-using Gradle and understand how to build your own packages, move onto the
-[next section](#adding-the-gitlab-package-registry-as-a-maven-remote).
+If you already use Gradle and know how to build your own packages, go to the
+[next section](#add-the-package-registry-as-a-maven-remote).
 
-### Installing Gradle
+### Install Gradle
 
 Installation is needed only if you want to create a new Gradle project. Follow
 instructions at [gradle.org](https://gradle.org/install/) to download and install
@@ -145,7 +125,7 @@ JVM:          11.0.5 (Oracle Corporation 11.0.5+10)
 OS:           Windows 10 10.0 amd64
 ```
 
-### Creating a project in Gradle
+### Create a Java project
 
 Understanding how to create a full Java project in Gradle is outside the scope of this
 guide, but you can follow the steps below to create a new project that can be
@@ -209,23 +189,23 @@ Project name (default: test):
 
 Enter a project name or hit enter to use the directory name as project name.
 
-## Adding the GitLab Package Registry as a Maven remote
+## Add the Package Registry as a Maven remote
 
 The next step is to add the GitLab Package Registry as a Maven remote. If a
 project is private or you want to upload Maven artifacts to GitLab,
 credentials must be provided for authorization too. Support is available
-for [personal access tokens](#authenticating-with-a-personal-access-token),
-[CI job tokens](#authenticating-with-a-ci-job-token), and
+for [personal access tokens](#authenticate-with-a-personal-access-token),
+[CI job tokens](#authenticate-with-a-ci-job-token), and
 [deploy tokens](../../project/deploy_tokens/index.md) only. Regular username/password
 credentials do not work.
 
-### Authenticating with a personal access token
+### Authenticate with a personal access token
 
 To authenticate with a [personal access token](../../profile/personal_access_tokens.md),
 set the scope to `api` when creating one, and add it to your Maven or Gradle configuration
 files.
 
-#### Authenticating with a personal access token in Maven
+#### Authenticate with a personal access token in Maven
 
 Add a corresponding section to your
 [`settings.xml`](https://maven.apache.org/settings.html) file:
@@ -248,7 +228,7 @@ Add a corresponding section to your
 </settings>
 ```
 
-#### Authenticating with a personal access token in Gradle
+#### Authenticate with a personal access token in Gradle
 
 Create a file `~/.gradle/gradle.properties` with the following content:
 
@@ -278,12 +258,12 @@ repositories {
 
 You should now be able to upload Maven artifacts to your project.
 
-### Authenticating with a CI job token
+### Authenticate with a CI job token
 
 If you're using GitLab CI/CD, a CI job token can be used instead
 of a personal access token.
 
-#### Authenticating with a CI job token in Maven
+#### Authenticate with a CI job token in Maven
 
 To authenticate with a CI job token, add a corresponding section to your
 [`settings.xml`](https://maven.apache.org/settings.html) file:
@@ -309,7 +289,7 @@ To authenticate with a CI job token, add a corresponding section to your
 You can read more on
 [how to create Maven packages using GitLab CI/CD](#creating-maven-packages-with-gitlab-cicd).
 
-#### Authenticating with a CI job token in Gradle
+#### Authenticate with a CI job token in Gradle
 
 To authenticate with a CI job token, add a repositories section to your
 [`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html)
@@ -331,7 +311,7 @@ repositories {
 }
 ```
 
-### Authenticating with a deploy token
+### Authenticate with a deploy token
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/213566) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.0.
 
@@ -339,7 +319,7 @@ To authenticate with a [deploy token](./../../project/deploy_tokens/index.md),
 set the scope to `api` when creating one, and add it to your Maven or Gradle configuration
 files.
 
-#### Authenticating with a deploy token in Maven
+#### Authenticate with a deploy token in Maven
 
 Add a corresponding section to your
 [`settings.xml`](https://maven.apache.org/settings.html) file:
@@ -362,7 +342,7 @@ Add a corresponding section to your
 </settings>
 ```
 
-#### Authenticating with a deploy token in Gradle
+#### Authenticate with a deploy token in Gradle
 
 To authenticate with a deploy token, add a repositories section to your
 [`build.gradle`](https://docs.gradle.org/current/userguide/tutorial_using_tasks.html)
@@ -441,7 +421,7 @@ repositories {
 ```
 
 The `id` must be the same with what you
-[defined in `settings.xml`](#adding-the-gitlab-package-registry-as-a-maven-remote).
+[defined in `settings.xml`](#add-the-package-registry-as-a-maven-remote).
 
 Replace `PROJECT_ID` with your project ID which can be found on the home page
 of your project.
@@ -452,7 +432,7 @@ domain name.
 NOTE: **Note:**
 For retrieving artifacts, you can use either the
 [URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project
-(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the
+(such as `group%2Fproject`) or the project's ID (such as `42`). However, only the
 project's ID can be used for uploading.
 
 ### Group level Maven endpoint
@@ -505,7 +485,7 @@ repositories {
 ```
 
 The `id` must be the same with what you
-[defined in `settings.xml`](#adding-the-gitlab-package-registry-as-a-maven-remote).
+[defined in `settings.xml`](#add-the-package-registry-as-a-maven-remote).
 
 Replace `my-group` with your group name and `PROJECT_ID` with your project ID
 which can be found on the home page of your project.
@@ -516,7 +496,7 @@ domain name.
 NOTE: **Note:**
 For retrieving artifacts, you can use either the
 [URL encoded](../../../api/README.md#namespaced-path-encoding) path of the group
-(e.g., `group%2Fsubgroup`) or the group's ID (e.g., `12`).
+(such as `group%2Fsubgroup`) or the group's ID (such as `12`).
 
 ### Instance level Maven endpoint
 
@@ -571,7 +551,7 @@ repositories {
 ```
 
 The `id` must be the same with what you
-[defined in `settings.xml`](#adding-the-gitlab-package-registry-as-a-maven-remote).
+[defined in `settings.xml`](#add-the-package-registry-as-a-maven-remote).
 
 Replace `PROJECT_ID` with your project ID which can be found on the home page
 of your project.
@@ -582,12 +562,12 @@ domain name.
 NOTE: **Note:**
 For retrieving artifacts, you can use either the
 [URL encoded](../../../api/README.md#namespaced-path-encoding) path of the project
-(e.g., `group%2Fproject`) or the project's ID (e.g., `42`). However, only the
+(such as `group%2Fproject`) or the project's ID (such as `42`). However, only the
 project's ID can be used for uploading.
 
 ## Uploading packages
 
-Once you have set up the [remote and authentication](#adding-the-gitlab-package-registry-as-a-maven-remote)
+Once you have set up the [remote and authentication](#add-the-package-registry-as-a-maven-remote)
 and [configured your project](#configuring-your-project-to-use-the-gitlab-maven-repository-url),
 test to upload a Maven artifact from a project of yours.
 
@@ -661,7 +641,7 @@ artifacts or even delete them.
 ## Installing a package
 
 Installing a package from the GitLab Package Registry requires that you set up
-the [remote and authentication](#adding-the-gitlab-package-registry-as-a-maven-remote)
+the [remote and authentication](#add-the-package-registry-as-a-maven-remote)
 as above. Once this is completed, there are two ways to install a package.
 
 ### Install using Maven with `mvn install`
@@ -708,7 +688,7 @@ Package details page, allowing for quick and easy installation.
 
 ### Install using Gradle
 
-Add a [dependency](https://docs.gradle.org/current/userguide/declaring_dependencies.html) to build.gradle in the dependencies section:
+Add a [dependency](https://docs.gradle.org/current/userguide/declaring_dependencies.html) to `build.gradle` in the dependencies section:
 
 ```groovy
 dependencies {
@@ -802,7 +782,7 @@ Docker container), and Maven uses the configured CI
 The example below shows how to create a new package each time the `master` branch
 is updated:
 
-1. Make sure you use the Job-Token authentication as described in ["Authenticating with a CI job token in Gradle"](#authenticating-with-a-ci-job-token-in-gradle).
+1. Make sure you use the Job-Token authentication as described in ["Authenticating with a CI job token in Gradle"](#authenticate-with-a-ci-job-token-in-gradle).
 
 1. Add a `deploy` job to your `.gitlab-ci.yml` file:
 

doc/user/packages/workflows/project_registry.md

@@ -26,8 +26,8 @@ point them at the same project on GitLab.
 There are a few reasons you might want to publish all your packages to one project on GitLab:
 
 1. You want to publish your packages on GitLab, but to a project that is different from where your code is stored.
-1. You would like to group packages together in ways that make sense for your usage (all NPM packages in one project,
-   all packages being used by a specific department in one project, all private packages in one project, etc.)
+1. You would like to group packages together in ways that make sense for your usage (such as all NPM packages in one project,
+   all packages being used by a specific department in one project, or all private packages in one project)
 1. You want to use one remote for all of your packages when installing them into other projects.
 1. You would like to migrate your packages to a single place on GitLab from a third-party package registry and do not
    want to worry about setting up separate projects for each package.
@@ -44,7 +44,7 @@ Let's take a look at how you might create a public place to hold all of your pub
 ### Create a project
 
 First, create a new project on GitLab. It does not have to have any code or content. Make note of the project ID
-displayed on the project overview page, as you will need this later.
+displayed on the project overview page for use later in this process.
 
 ### Create an access token
 
@@ -67,15 +67,15 @@ If you are using NPM, this involves creating an `.npmrc` file and adding the app
 to your project using your project ID, then adding a section to your `package.json` file with a similar URL.
 
 Follow
-the instructions in the [GitLab NPM Registry documentation](../npm_registry/index.md#authenticating-to-the-gitlab-npm-registry). Once
-you do this, you will be able to push your NPM package to your project using `npm publish`, as described in the
+the instructions in the [GitLab NPM Registry documentation](../npm_registry/index.md#authenticating-to-the-gitlab-npm-registry). After
+you do this, you can push your NPM package to your project using `npm publish`, as described in the
 [uploading packages](../npm_registry/index.md#uploading-packages) section of the docs.
 
 #### Maven
 
 If you are using Maven, this involves updating your `pom.xml` file with distribution sections, including the
 appropriate URL for your project, as described in the [GitLab Maven Repository documentation](../maven_repository/index.md#project-level-maven-endpoint).
-Then, you need to add a `settings.xml` file and [include your access token](../maven_repository/index.md#authenticating-with-a-personal-access-token).
+Then, you need to add a `settings.xml` file and [include your access token](../maven_repository/index.md#authenticate-with-a-personal-access-token).
 Now you can [deploy Maven packages](../maven_repository/index.md#uploading-packages) to your project.
 
 #### Conan
@@ -83,7 +83,7 @@ Now you can [deploy Maven packages](../maven_repository/index.md#uploading-packa
 For Conan, first you need to add GitLab as a Conan registry remote. Follow the instructions in the [GitLab Conan Repository docs](../conan_repository/index.md#add-the-package-registry-as-a-conan-remote)
 to do so. Then, create your package using the plus-separated (`+`) project path as your Conan user. For example,
 if your project is located at `https://gitlab.com/foo/bar/my-proj`, then you can [create your Conan package](../conan_repository/index.md)
-using `conan create . foo+bar+my-proj/channel`, where `channel` is your package channel (`stable`, `beta`, etc.). Once your package
+using `conan create . foo+bar+my-proj/channel`, where `channel` is your package channel (such as `stable` or `beta`). After your package
 is created, you are ready to [upload your package](../conan_repository/index.md#publish-a-conan-package) depending on your final package recipe. For example:
 
 ```shell