Add latest changes from gitlab-org/gitlab@master

1 files changed, 504 insertions, 0 deletions

diff --git a/doc/user/packages/workflows/build_packages.md b/doc/user/packages/workflows/build_packages.md
new file mode 100644
index 00000000000..063217f0ad7
--- /dev/null
+++ b/doc/user/packages/workflows/build_packages.md
@@ -0,0 +1,504 @@
+---
+stage: Package
+group: Package Registry
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
+---
+
+# Build packages
+
+Learn how to install and build packages different package formats.
+
+- [Composer](#composer)
+- [Conan](#conan)
+- [Maven](#maven)
+- [Gradle](#gradle)
+- [npm](#npm)
+- [Yarn](#yarn)
+- [NuGet](#nuget)
+- [PyPI](#pypi)
+
+## Composer
+
+1. Create a directory called `my-composer-package` and change to that directory:
+
+   ```shell
+   mkdir my-composer-package && cd my-composer-package
+   ```
+
+1. Run [`composer init`](https://getcomposer.org/doc/03-cli.md#init) and answer the prompts.
+
+   For namespace, enter your unique [namespace](../../../user/namespace/index.md), like your GitLab username or group name.
+
+   A file called `composer.json` is created:
+
+   ```json
+   {
+     "name": "<namespace>/composer-test",
+     "description": "Library XY",
+     "type": "library",
+     "license": "GPL-3.0-only",
+     "authors": [
+       {
+         "name": "John Doe",
+         "email": "john@example.com"
+       }
+     ],
+     "require": {}
+   }
+   ```
+
+## Conan
+
+### Install Conan
+
+Download the Conan package manager to your local development environment by
+following the instructions at [conan.io](https://conan.io/downloads.html).
+
+When installation is complete, verify you can use Conan in your terminal by
+running:
+
+```shell
+conan --version
+```
+
+The Conan version is printed in the output:
+
+```plaintext
+Conan version 1.20.5
+```
+
+### Install CMake
+
+When you develop with C++ and Conan, you can select from many available
+compilers. This example uses the CMake build system generator.
+
+To install CMake:
+
+- For Mac, use [Homebrew](https://brew.sh/) and run `brew install cmake`.
+- For other operating systems, follow the instructions at [cmake.org](https://cmake.org/install/).
+
+When installation is complete, verify you can use CMake in your terminal by
+running:
+
+```shell
+cmake --version
+```
+
+The CMake version is printed in the output.
+
+### Create a project
+
+To test the Package Registry, you need a C++ project. If you don't already have
+one, you can clone the Conan [hello world starter project](https://github.com/conan-io/hello).
+
+### Build a Conan package
+
+To build a package:
+
+1. Open a terminal and navigate to your project's root folder.
+1. Generate a new recipe by running `conan new` with a package name and version:
+
+   ```shell
+   conan new Hello/0.1 -t
+   ```
+
+1. Create a package for the recipe by running `conan create` with the Conan user
+   and channel:
+
+   ```shell
+   conan create . mycompany/beta
+   ```
+
+   NOTE:
+   If you use an [instance remote](../conan_repository/index.md#add-a-remote-for-your-instance), you must
+   follow a specific [naming convention](../conan_repository/index.md#package-recipe-naming-convention-for-instance-remotes).
+
+A package with the recipe `Hello/0.1@mycompany/beta` is created.
+
+For more details about creating and managing Conan packages, see the
+[Conan documentation](https://docs.conan.io/en/latest/creating_packages.html).
+
+## Maven
+
+### Install Maven
+
+The required minimum versions are:
+
+- Java 11.0.5+
+- Maven 3.6+
+
+Follow the instructions at [maven.apache.org](https://maven.apache.org/install.html)
+to download and install Maven for your local development environment. After
+installation is complete, verify you can use Maven in your terminal by running:
+
+```shell
+mvn --version
+```
+
+The output should be similar to:
+
+```shell
+Apache Maven 3.6.1 (d66c9c0b3152b2e69ee9bac180bb8fcc8e6af555; 2019-04-04T20:00:29+01:00)
+Maven home: /Users/<your_user>/apache-maven-3.6.1
+Java version: 12.0.2, vendor: Oracle Corporation, runtime: /Library/Java/JavaVirtualMachines/jdk-12.0.2.jdk/Contents/Home
+Default locale: en_GB, platform encoding: UTF-8
+OS name: "mac os x", version: "10.15.2", arch: "x86_64", family: "mac"
+```
+
+### Build a Maven package
+
+1. Open your terminal and create a directory to store the project.
+1. From the new directory, run this Maven command to initialize a new package:
+
+   ```shell
+   mvn archetype:generate -DgroupId=com.mycompany.mydepartment -DartifactId=my-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
+   ```
+
+   The arguments are:
+
+   - `DgroupId`: A unique string that identifies your package. Follow
+     the [Maven naming conventions](https://maven.apache.org/guides/mini/guide-naming-conventions.html).
+   - `DartifactId`: The name of the `JAR`, appended to the end of the `DgroupId`.
+   - `DarchetypeArtifactId`: The archetype used to create the initial structure of
+     the project.
+   - `DinteractiveMode`: Create the project using batch mode (optional).
+
+This message indicates that the project was set up successfully:
+
+```shell
+...
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESS
+[INFO] ------------------------------------------------------------------------
+[INFO] Total time:  3.429 s
+[INFO] Finished at: 2020-01-28T11:47:04Z
+[INFO] ------------------------------------------------------------------------
+```
+
+In the folder where you ran the command, a new directory should be displayed.
+The directory name should match the `DartifactId` parameter, which in this case,
+is `my-project`.
+
+## Gradle
+
+### Install Gradle
+
+If you want to create a new Gradle project, you must install Gradle. Follow
+instructions at [gradle.org](https://gradle.org/install/) to download and install
+Gradle for your local development environment.
+
+In your terminal, verify you can use Gradle by running:
+
+```shell
+gradle -version
+```
+
+To use an existing Gradle project, in the project directory,
+on Linux execute `gradlew`, or on Windows execute `gradlew.bat`.
+
+The output should be similar to:
+
+```plaintext
+------------------------------------------------------------
+Gradle 6.0.1
+------------------------------------------------------------
+
+Build time:   2019-11-18 20:25:01 UTC
+Revision:     fad121066a68c4701acd362daf4287a7c309a0f5
+
+Kotlin:       1.3.50
+Groovy:       2.5.8
+Ant:          Apache Ant(TM) version 1.10.7 compiled on September 1 2019
+JVM:          11.0.5 (Oracle Corporation 11.0.5+10)
+OS:           Windows 10 10.0 amd64
+```
+
+### Create a package
+
+1. Open your terminal and create a directory to store the project.
+1. From this new directory, run this command to initialize a new package:
+
+   ```shell
+   gradle init
+   ```
+
+   The output should be:
+
+   ```plaintext
+   Select type of project to generate:
+     1: basic
+     2: application
+     3: library
+     4: Gradle plugin
+   Enter selection (default: basic) [1..4]
+   ```
+
+1. Enter `3` to create a new Library project. The output should be:
+
+   ```plaintext
+   Select implementation language:
+     1: C++
+     2: Groovy
+     3: Java
+     4: Kotlin
+     5: Scala
+     6: Swift
+   ```
+
+1. Enter `3` to create a new Java Library project. The output should be:
+
+   ```plaintext
+   Select build script DSL:
+     1: Groovy
+     2: Kotlin
+   Enter selection (default: Groovy) [1..2]
+   ```
+
+1. Enter `1` to create a new Java Library project that is described in Groovy DSL, or `2` to create one that is described in Kotlin DSL. The output should be:
+
+   ```plaintext
+   Select test framework:
+     1: JUnit 4
+     2: TestNG
+     3: Spock
+     4: JUnit Jupiter
+   ```
+
+1. Enter `1` to initialize the project with JUnit 4 testing libraries. The output should be:
+
+   ```plaintext
+   Project name (default: test):
+   ```
+
+1. Enter a project name or press <kbd>Enter</kbd> to use the directory name as project name.
+
+## npm
+
+### Install npm
+
+Install Node.js and npm in your local development environment by following
+the instructions at [npmjs.com](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm/).
+
+When installation is complete, verify you can use npm in your terminal by
+running:
+
+```shell
+npm --version
+```
+
+The npm version is shown in the output:
+
+```plaintext
+6.10.3
+```
+
+### Create an npm package
+
+1. Create an empty directory.
+1. Go to the directory and initialize an empty package by running:
+
+   ```shell
+   npm init
+   ```
+
+1. Enter responses to the questions. Ensure the **package name** follows
+   the [naming convention](../npm_registry/index.md#package-naming-convention) and is scoped to the project or group where the registry exists.
+
+## Yarn
+
+### Install Yarn
+
+As an alternative to npm, you can install Yarn in your local environment by following the
+instructions at [classic.yarnpkg.com](https://classic.yarnpkg.com/en/docs/install).
+
+When installation is complete, verify you can use Yarn in your terminal by
+running:
+
+```shell
+yarn --version
+```
+
+The Yarn version is shown in the output:
+
+```plaintext
+1.19.1
+```
+
+### Create a package
+
+1. Create an empty directory.
+1. Go to the directory and initialize an empty package by running:
+
+   ```shell
+   yarn init
+   ```
+
+1. Enter responses to the questions. Ensure the **package name** follows
+   the [naming convention](../npm_registry/index.md#package-naming-convention) and is scoped to the
+   project or group where the registry exists.
+
+A `package.json` file is created.
+
+## NuGet
+
+### Install NuGet
+
+Follow the instructions from [https://learn.microsoft.com/en-us/nuget/install-nuget-client-tools] Microsoft to install NuGet. If you have
+[Visual Studio](https://visualstudio.microsoft.com/vs/), NuGet is
+probably already installed.
+
+Verify that the [NuGet CLI](https://www.nuget.org/) is installed by running:
+
+```shell
+nuget help
+```
+
+The output should be similar to:
+
+```plaintext
+NuGet Version: 5.1.0.6013
+usage: NuGet <command> [args] [options]
+Type 'NuGet help <command>' for help on a specific command.
+
+Available commands:
+
+[output truncated]
+```
+
+## PyPI
+
+### Install pip and twine
+
+Install a recent version of [pip](https://pypi.org/project/pip/) and
+[twine](https://pypi.org/project/twine/).
+
+### Create a project
+
+Create a test project.
+
+1. Open your terminal.
+1. Create a directory called `MyPyPiPackage`, and then go to that directory:
+
+   ```shell
+   mkdir MyPyPiPackage && cd MyPyPiPackage
+   ```
+
+1. Create another directory and go to it:
+
+   ```shell
+   mkdir mypypipackage && cd mypypipackage
+   ```
+
+1. Create the required files in this directory:
+
+   ```shell
+   touch __init__.py
+   touch greet.py
+   ```
+
+1. Open the `greet.py` file, and then add:
+
+   ```python
+   def SayHello():
+       print("Hello from MyPyPiPackage")
+       return
+   ```
+
+1. Open the `__init__.py` file, and then add:
+
+   ```python
+   from .greet import SayHello
+   ```
+
+1. To test the code, in your `MyPyPiPackage` directory, start the Python prompt.
+
+   ```shell
+   python
+   ```
+
+1. Run this command:
+
+   ```python
+   >>> from mypypipackage import SayHello
+   >>> SayHello()
+   ```
+
+A message indicates that the project was set up successfully:
+
+```plaintext
+Python 3.8.2 (v3.8.2:7b3ab5921f, Feb 24 2020, 17:52:18)
+[Clang 6.0 (clang-600.0.57)] on darwin
+Type "help", "copyright", "credits" or "license" for more information.
+>>> from mypypipackage import SayHello
+>>> SayHello()
+Hello from MyPyPiPackage
+```
+
+### Create a PyPI package
+
+After you create a project, you can create a package.
+
+1. In your terminal, go to the `MyPyPiPackage` directory.
+1. Create a `pyproject.toml` file:
+
+   ```shell
+   touch pyproject.toml
+   ```
+
+   This file contains all the information about the package. For more information
+   about this file, see [creating `pyproject.toml`](https://packaging.python.org/en/latest/tutorials/packaging-projects/#creating-pyproject-toml).
+   Because GitLab identifies packages based on
+   [Python normalized names (PEP-503)](https://www.python.org/dev/peps/pep-0503/#normalized-names),
+   ensure your package name meets these requirements. See the [installation section](../pypi_repository/index.md#authenticate-with-a-ci-job-token)
+   for details.
+
+1. Open the `pyproject.toml` file, and then add basic information:
+
+   ```toml
+   [build-system]
+   requires = ["setuptools>=61.0"]
+   build-backend = "setuptools.build_meta"
+
+   [project]
+   name = "mypypipackage"
+   version = "0.0.1"
+   authors = [
+       { name="Example Author", email="author@example.com" },
+   ]
+   description = "A small example package"
+   requires-python = ">=3.7"
+   classifiers = [
+      "Programming Language :: Python :: 3",
+      "Operating System :: OS Independent",
+   ]
+
+   [tool.setuptools.packages]
+   find = {}
+   ```
+
+1. Save the file.
+1. Install the package build library:
+
+   ```shell
+   pip install build
+   ```
+
+1. Build the package:
+
+   ```shell
+   python -m build
+   ```
+
+The output should be visible in a newly-created `dist` folder:
+
+```shell
+ls dist
+```
+
+The output should appear similar to the following:
+
+```plaintext
+mypypipackage-0.0.1-py3-none-any.whl mypypipackage-0.0.1.tar.gz
+```
+
+The package is now ready to be published to the Package Registry.