Merge branch 'trizzi-master-patch-a15e' into 'master'

Package registry docs review Q3

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/168134



Merged-by: Amy Qualls <aqualls@gitlab.com>
Approved-by: David Fernandez <dfernandez@gitlab.com>
Approved-by: Amy Qualls <aqualls@gitlab.com>
Reviewed-by: David Fernandez <dfernandez@gitlab.com>
Reviewed-by: Amy Qualls <aqualls@gitlab.com>
Co-authored-by: phillipwells <pwells@gitlab.com>
Co-authored-by: Tim Rizzi <trizzi@gitlab.com>

doc/user/packages/npm_registry/index.md

@@ -10,25 +10,240 @@ DETAILS:
 **Tier:** Free, Premium, Ultimate
 **Offering:** GitLab.com, Self-managed, GitLab Dedicated
+Node Package Manager (npm) is the default package manager for JavaScript and Node.js. Developers use npm to share and reuse code, manage dependencies, and streamline project workflows. In GitLab, npm packages play a crucial role in the software development lifecycle.
+
 For documentation of the specific API endpoints that the npm package manager client uses, see the [npm API documentation](../../../api/packages/npm.md).
 Learn how to build an [npm](../workflows/build_packages.md#npm) or [yarn](../workflows/build_packages.md#yarn) package.
 Watch a [video demo](https://youtu.be/yvLxtkvsFDA) of how to publish npm packages to the GitLab package registry.
-## Publish to GitLab package registry
-### Authentication to the package registry
-You need a token to publish a package. There are different tokens available depending on what you're trying to achieve. For more information, review the [guidance on tokens](../../../user/packages/package_registry/index.md#authenticate-with-the-registry).
-- If your organization uses two factor authentication (2FA), you must use a personal access token with the scope set to `api`.
-- If you are publishing a package via CI/CD pipelines, you must use a CI job token.
-Create a token and save it to use later in the process.
+## Authenticate to the package registry
+You must authenticate to the package registry to publish or install a package from a private project or a private group.
+You don't need to authenticate if the project or the group is public.
+If the project is internal, you must be a registered user on the GitLab instance.
+An anonymous user cannot pull packages from an internal project.
+To authenticate, you can use:
+- A [personal access token](../../../user/profile/personal_access_tokens.md)
+  with the scope set to `api`.
+- A [deploy token](../../project/deploy_tokens/index.md) with the scope set to
+  `read_package_registry`, `write_package_registry`, or both.
+- A [CI job token](../../../ci/jobs/ci_job_token.md).
+If your organization uses two-factor authentication (2FA), you must use a personal access token with the scope set to `api`.
+If you are publishing a package via CI/CD pipelines, you must use a CI job token.
+For more information, review the [guidance on tokens](../../../user/packages/package_registry/index.md#authenticate-with-the-registry).
 Do not use authentication methods other than the methods documented here. Undocumented authentication methods might be removed in the future.
+### Authenticate with the `.npmrc`
+
+Create or edit the `.npmrc` file in the same directory as your `package.json`. Include the following lines in the `.npmrc` file:
+
+```shell
+  //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"
+```
+
+If you're installing:
+
+- From an instance:
+
+  ```shell
+  //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"
+  ```
+
+- From a group:
+
+  ```shell
+  //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"
+  ```
+
+- From a project:
+
+  ```shell
+  //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"
+  ```
+
+In these examples:
+
+- Replace `your_domain_name` with your domain name, for example, `gitlab.com`.
+- Replace `your_group_id` with your group ID, found on the group's home page.
+- Replace `your_project_id` with your project ID, found on the [project overview page](../../project/working_with_projects.md#access-a-project-by-using-the-project-id).
+- Replace `your_token` with a deploy token, group access token, project access token, or personal access token.
+
+WARNING:
+Never hardcode GitLab tokens (or any tokens) directly in `.npmrc` files or any other files that can
+be committed to a repository.
+
+### Authenticate with `npm config set`
+
+To do this:
+
+```shell
+npm config set -- //your_domain_name/:_authToken=your_token
+```
+
+With npm version 7 or earlier, use the full URL to the endpoint.
+
+If you're installing:
+
+- From an instance:
+
+  ```shell
+  npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token
+  ```
+
+- From a group:
+
+  ```shell
+  npm config set -- //your_domain_name/api/v4/groups/your_group_id/-/packages/npm/:_authToken=your_token
+  ```
+
+- From a project:
+
+  ```shell
+  npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token
+  ```
+
+In these examples:
+
+- Replace `your_domain_name` with your domain name, for example, `gitlab.com`.
+- Replace `your_group_id` with your group ID, found on the group's home page.
+- Replace `your_project_id` with your project ID, found on the [project overview page](../../project/working_with_projects.md#access-a-project-by-using-the-project-id).
+- Replace `your_token` with a deploy token, group access token, project access token, or personal access token.
+
+NOTE:
+In npm versions 8 and later, you can [use a URI fragment instead of a full URL](https://docs.npmjs.com/cli/v8/configuring-npm/npmrc/?v=true#auth-related-configuration)
+in the `_authToken` parameter. However, [group-specific endpoints](https://gitlab.com/gitlab-org/gitlab/-/issues/299834)
+are not supported.
+
+## Set up the registry URL
+
+To publish or install packages from the GitLab Package Registry, you need to configure npm to use the correct registry URL. The configuration method and URL structure depend on whether you're publishing or installing packages.
+
+Before configuring the registry URL, it's important to understand the scope of different configuration methods:
+
+- `.npmrc` file: Configuration is local to the folder containing the file.
+- `npm config set` command: This modifies the global npm configuration and affects all npm commands run on your system.
+- `publishConfig` in `package.json`: This configuration is specific to the package and only applies when publishing that package.
+
+WARNING:
+Running `npm config set` changes the global npm configuration. The change affects all npm commands
+run on your system, regardless of the current working directory. Be cautious when using this method,
+especially on shared systems.
+
+### For publishing packages
+
+When publishing packages, use the project endpoint. The URL structure is:
+
+`https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/`
+
+Replace `gitlab.example.com` with your GitLab instance's domain and `<project_id>` with your project's ID.
+To configure this URL, use one of these methods:
+
+::Tabs
+
+:::TabTitle `.npmrc` file
+
+Create or edit the `.npmrc` file in your project root: 
+
+```plaintext
+@scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/ //gitlab.example.com/api/v4/projects/<project_id>/packages/npm/:_authToken="${NPM_TOKEN}"
+```
+
+:::TabTitle `npm config`
+
+Use the `npm config set` command:
+
+```shell
+npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
+```
+
+:::TabTitle `package.json`
+
+Add a publishConfig section to your `package.json`:
+
+```shell
+{
+  "publishConfig": {
+    "@scope:registry": "https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/"
+  }
+}
+```
+
+::EndTabs
+
+Replace `@scope` with your package's scope.
+
+### For installing packages
+
+When installing packages, you can use project, group, or instance-level endpoints. The URL structure varies accordingly:
+
+You can configure these URLs using one of the following methods:
+
+When you install packages, you can use project, group, or instance endpoints. The URL structure varies accordingly.
+To configure these URLs, use one of these methods:
+
+::Tabs
+
+:::TabTitle `.npmrc` file 
+
+Create or edit the `.npmrc` file in your project root. Use the appropriate URL based on your needs:
+
+- For a project:
+
+  ```shell
+  npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
+  ```
+
+- For a group:
+
+  ```shell
+  npm config set @scope:registry=https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/
+  ```
+
+- For an instance:
+
+  ```shell
+  npm config set @scope:registry=https://gitlab.example.com/api/v4/packages/npm/
+  ```
+
+:::TabTitle `npm config`
+
+Use the `npm config set` command with the appropriate URL:
+
+- For a project:
+
+  ```shell
+  npm config set @scope:registry=https://gitlab.example.com/api/v4/projects/<project_id>/packages/npm/
+  ```
+
+- For a group:
+
+  ```shell
+  npm config set @scope:registry=https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/npm/
+  ```
+
+- For an instance:
+
+  ```shell
+  npm config set @scope:registry=https://gitlab.example.com/api/v4/packages/npm/
+  ```
+
+::EndTabs
+
+Replace `gitlab.example.com`, `<project_id>`, `<group_id>`, and `@scope` with the appropriate values for your GitLab instance and package.
+
+After you configure your registry URL, set up authentication as described in the authentication section.
+
+## Publish to GitLab package registry
+
+To publish an npm package to the GitLab package registry, you must be
+[authenticated](#authenticate-to-the-package-registry).
+
 ### Naming convention
 Depending on how the package is installed, you may need to adhere to the naming convention.
@@ -61,29 +276,15 @@ Make sure that the name of your package in the `package.json` file matches this
 "name": "@my-org/package-name"
 ```
-## Publishing a package via the command line
-
-### Authenticating via the `.npmrc`
-Create or edit the `.npmrc` file in the same directory as your `package.json`. Include the following lines in the `.npmrc` file:
+### Publishing a package via the command line
+After you [configure authentication](#authenticate-to-the-package-registry), publish the NPM package with:
 ```shell
-@scope:registry=https://your_domain_name/api/v4/projects/your_project_id/packages/npm/
-//your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken="${NPM_TOKEN}"
+npm publish
 ```
-- Replace `@scope` with the [root level group](#naming-convention) of the project you're publishing to the package to.
-- Replace `your_domain_name` with your domain name, for example, `gitlab.com`.
-- Replace `your_project_id` with your project ID, found on the [project overview page](../../project/working_with_projects.md#access-a-project-by-using-the-project-id).
-- `"${NPM_TOKEN}"` is associated with the token you created later in the process.
-
-WARNING:
-Never hardcode GitLab tokens (or any tokens) directly in `.npmrc` files or any other files that can
-be committed to a repository.
-
-### Publishing a package via the command line
-
-Associate your [token](#authentication-to-the-package-registry) with the `"${NPM_TOKEN}"` in the `.npmrc`. Replace `your_token` with a deploy token, group access token, project access token, or personal access token.
+If you're using an `.npmrc` file for authentication, set the expected environment variables:
 ```shell
 NPM_TOKEN=your_token npm publish
@@ -95,7 +296,7 @@ If the uploaded package has more than one `package.json` file, only the first on
 ## Publishing a package by using a CI/CD pipeline
-When publishing by using a CI/CD pipeline, you can use the [predefined variables](../../../ci/variables/predefined_variables.md) `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}` to authenticate with your project's package registry. We use these variables to create a `.npmrc` file [for authentication](#authenticating-via-the-npmrc) during execution of your CI/CD job.
+When publishing by using a CI/CD pipeline, you can use the [predefined variables](../../../ci/variables/predefined_variables.md) `${CI_PROJECT_ID}` and `${CI_JOB_TOKEN}` to authenticate with your project's package registry. We use these variables to create a `.npmrc` file [for authentication](#authenticate-with-the-npmrc) during execution of your CI/CD job.
 WARNING:
 When generating the `.npmrc` file, do not specify the port after `${CI_SERVER_HOST}` if it is a default port,
@@ -131,53 +332,6 @@ You can install a package from a GitLab project, group, or instance:
 - **Group**: Use when you have many npm packages in different projects in the same GitLab group.
 - **Project**: Use when you have few npm packages and they are not in the same GitLab group.
-### Authenticate to the package registry
-
-You must authenticate to the package registry to install a package from a private project or a private group.
-No authentication is needed if the project or the group is public.
-If the project is internal, you must be a registered user on the GitLab instance.
-An anonymous user cannot pull packages from an internal project.
-
-To authenticate with `npm`:
-
-```shell
-npm config set -- //your_domain_name/:_authToken=your_token
-```
-
-With npm version 7 or earlier, use the full URL to the endpoint.
-
-If you're installing:
-
-- From an instance:
-
-  ```shell
-  npm config set -- //your_domain_name/api/v4/packages/npm/:_authToken=your_token
-  ```
-
-- From a group:
-
-  ```shell
-  npm config set -- //your_domain_name/api/v4/groups/your_group_id/-/packages/npm/:_authToken=your_token
-  ```
-
-- From a project:
-
-  ```shell
-  npm config set -- //your_domain_name/api/v4/projects/your_project_id/packages/npm/:_authToken=your_token
-  ```
-
-In these examples:
-
-- Replace `your_domain_name` with your domain name, for example, `gitlab.com`.
-- Replace `your_group_id` with your group ID, found on the group's home page.
-- Replace `your_project_id` with your project ID, found on the [project overview page](../../project/working_with_projects.md#access-a-project-by-using-the-project-id).
-- Replace `your_token` with a deploy token, group access token, project access token, or personal access token.
-
-NOTE:
-Starting with npm version 8, you can [use a URI fragment instead of a full URL](https://docs.npmjs.com/cli/v8/configuring-npm/npmrc/?v=true#auth-related-configuration)
-in the `_authToken` parameter. However, [group-specific endpoints](https://gitlab.com/gitlab-org/gitlab/-/issues/299834)
-are not supported.
-
 ### Install from an instance
 WARNING:
@@ -266,7 +420,7 @@ You can deprecate a package so that a deprecation warning displays when the pack
 Pre-requisites:
 - The same [permissions](../../permissions.md) as deleting a package.
-- [Authenticated to the package registry](#authentication-to-the-package-registry).
+- [Authenticated to the package registry](#authenticate-to-the-package-registry).
 From the command line, run:

doc/user/packages/pypi_repository/index.md

@@ -10,8 +10,10 @@ DETAILS:
 **Tier:** Free, Premium, Ultimate
 **Offering:** GitLab.com, Self-managed, GitLab Dedicated
-Publish PyPI packages in your project's package registry. Then install the
-packages whenever you need to use them as a dependency.
+The Python Package Index (PyPI) is the official third-party software repository for Python.
+Use the GitLab PyPI package registry to publish and share Python packages in your GitLab projects,
+groups, and organizations. This integration enables you to manage your Python dependencies alongside
+your code, providing a seamless workflow for Python development within GitLab.
 The package registry works with:
@@ -122,7 +124,7 @@ https://gitlab.example.com/api/v4/groups/<group_id>/-/packages/pypi
 Prerequisites:
 - You must [authenticate with the package registry](#authenticate-with-the-package-registry).
-- Your [version string must be valid](#ensure-your-version-string-is-valid).
+- Your [version string must be valid](#use-valid-version-strings).
 - The maximum allowed package size is 5 GB.
 - The maximum length of the `description` field is 4000 characters. Longer `description` strings are truncated.
 - You can't upload the same version of a package multiple times. If you try,
@@ -133,28 +135,6 @@ Prerequisites:
 You can then [publish a package by using twine](#publish-a-pypi-package-by-using-twine).
-### Ensure your version string is valid
-
-If your version string (for example, `0.0.1`) isn't valid, it gets rejected.
-GitLab uses the following regex to validate the version string.
-
-```ruby
-\A(?:
-    v?
-    (?:([0-9]+)!)?                                                 (?# epoch)
-    ([0-9]+(?:\.[0-9]+)*)                                          (?# release segment)
-    ([-_\.]?((a|b|c|rc|alpha|beta|pre|preview))[-_\.]?([0-9]+)?)?  (?# pre-release)
-    ((?:-([0-9]+))|(?:[-_\.]?(post|rev|r)[-_\.]?([0-9]+)?))?       (?# post release)
-    ([-_\.]?(dev)[-_\.]?([0-9]+)?)?                                (?# dev release)
-    (?:\+([a-z0-9]+(?:[-_\.][a-z0-9]+)*))?                         (?# local version)
-)\z}xi
-```
-
-You can experiment with the regex and try your version strings by using this
-[regular expression editor](https://rubular.com/r/FKM6d07ouoDaFV).
-
-For more details about the regex, review this [documentation](https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions).
-
 ### Publish a PyPI package by using twine
 To publish a PyPI package, run a command like:
@@ -227,13 +207,7 @@ pip install --index-url https://<personal_access_token_name>:<personal_access_to
 - `<project_id>` is either the project's [URL-encoded](../../../api/rest/index.md#namespaced-paths)
   path (for example, `group%2Fproject`), or the project's ID (for example `42`).
-In these commands, you can use `--extra-index-url` instead of `--index-url`. However, using
-`--extra-index-url` makes you vulnerable to dependency confusion attacks because it checks the PyPi
-repository for the package before it checks the custom repository. `--extra-index-url` adds the
-provided URL as an additional registry which the client checks if the package is present.
-`--index-url` tells the client to check for the package on the provided URL only.
-
-If you were following the guide and want to install the
+In these commands, you can use `--extra-index-url` instead of `--index-url`. If you were following the guide and want to install the
 `MyPyPiPackage` package, you can run:
 ```shell
@@ -250,6 +224,19 @@ Installing collected packages: mypypipackage
 Successfully installed mypypipackage-0.0.1
 ```
+#### Security implications
+
+The security implications of using `--extra-index-url` versus `--index-url` when installing PyPI
+packages are significant and worth understanding in detail. If you use:
+
+- `--index-url`: This option replaces the default [PyPI index](https://pypi.org)
+  with the specified URL. It's more secure because it only checks the specified index for packages.
+  Use this option when you want to ensure packages are only installed from a trusted, private source
+  (like the GitLab PyPI registry).
+- `--extra-index-url`: This option adds an additional index to search, alongside the default PyPI index.
+  It's less secure and more open to dependency confusion attacks, because it checks both the default PyPI
+  and the additional index for packages.
+
 ### Install from the group level
 To install the latest version of a package from a group, use the following command:
@@ -313,6 +300,45 @@ login __token__
 password <your_personal_token>
 ```
+## Versioning PyPI packages
+
+Proper versioning is important for managing PyPI packages effectively. Follow these best practices to ensure your packages are versioned correctly.
+
+### Use semantic versioning (SemVer)
+
+Adopt semantic versioning for your packages. The version number should be in the format `MAJOR.MINOR.PATCH`:
+
+- Increment `MAJOR` version for incompatible API changes.
+- Increment `MINOR` version for backwards-compatible new features.
+- Increment `PATCH` version for backwards-compatible bug fixes.
+
+For example: 1.0.0, 1.1.0, 1.1.1.
+
+#### Start with 0.1.0
+
+For new projects, start with version 0.1.0. This indicates an initial development phase where the API is not yet stable.
+
+### Use valid version strings
+
+Ensure your version string is valid according to PyPI standards. GitLab uses a specific regex to validate version strings:
+
+```ruby
+\A(?:
+    v?
+    (?:([0-9]+)!)?                                                 (?# epoch)
+    ([0-9]+(?:\.[0-9]+)*)                                          (?# release segment)
+    ([-_\.]?((a|b|c|rc|alpha|beta|pre|preview))[-_\.]?([0-9]+)?)?  (?# pre-release)
+    ((?:-([0-9]+))|(?:[-_\.]?(post|rev|r)[-_\.]?([0-9]+)?))?       (?# post release)
+    ([-_\.]?(dev)[-_\.]?([0-9]+)?)?                                (?# dev release)
+    (?:\+([a-z0-9]+(?:[-_\.][a-z0-9]+)*))?                         (?# local version)
+)\z}xi
+```
+
+You can experiment with the regex and try your version strings by using this
+[regular expression editor](https://rubular.com/r/FKM6d07ouoDaFV).
+
+For more details about the regex, see the [Python documentation](https://www.python.org/dev/peps/pep-0440/#appendix-b-parsing-version-strings-with-regular-expressions).
+
 ## Troubleshooting
 To improve performance, the pip command caches files related to a package. Pip doesn't remove data by

doc/user/packages/workflows/project_registry.md

@@ -60,7 +60,7 @@ If you're using npm, create an `.npmrc` file. Add the appropriate URL for publis
 packages to your project. Finally, add a section to your `package.json` file.
 Follow the instructions in the
-[GitLab package registry npm documentation](../npm_registry/index.md#authentication-to-the-package-registry). After
+[GitLab package registry npm documentation](../npm_registry/index.md#authenticate-to-the-package-registry). After
 you do this, you can publish your npm package to your project using `npm publish`, as described in the
 [publishing packages](../npm_registry/index.md#publish-to-gitlab-package-registry) section.