From c68ad062997ecf555dc40acec3a062d007915458 Mon Sep 17 00:00:00 2001 From: yahavi Date: Fri, 14 Jul 2023 14:45:35 +0300 Subject: [PATCH] Add CONTRIBUTING.md --- .github/PULL_REQUEST_TEMPLATE.md | 11 +- CONTRIBUTING.md | 297 ++++++++++++++++++++++++++++ README.md | 321 +------------------------------ 3 files changed, 305 insertions(+), 324 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index f10575440..cca3d0c4e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,5 +1,6 @@ -- [ ] All [tests](https://github.com/jfrog/jfrog-cli#tests) passed. If this feature is not already covered by the tests, I added new tests. -- [ ] All [static analysis checks](https://github.com/jfrog/jfrog-cli/actions/workflows/analysis.yml) passed. -- [ ] This pull request is on the dev branch. -- [ ] I used gofmt for formatting the code before submitting the pull request. ------ +- [ ] All [tests](https://github.com/jfrog/jfrog-cli/CONTRIBUTING.md#tests) have passed. If this feature is not already covered by the tests, new tests have been added. +- [ ] The pull request is targeting the `dev` branch. +- [ ] The code has been validated to compile successfully by running `go vet ./...`. +- [ ] The code has been formatted properly using `go fmt ./...`. + +--- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..d9bd3949d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,297 @@ +# 📖 Guidelines + +- Ensure that your changes are covered by existing tests. If not, please add new tests. +- Create pull requests on the `dev` branch. +- Before submitting the pull request, format the code by running `go fmt ./...`. +- Before submitting the pull request, ensure the code compiles by running `go vet ./...`. + +# ⚒️ Building and Testing the Sources + +## Building JFrog CLI + +To build JFrog CLI, first, make sure Go is installed by running the following command: + +```sh +go version +``` + +Next, clone the project sources and navigate to the root directory: + +```sh +git clone https://github.com/jfrog/jfrog-cli.git +cd jfrog-cli +``` + +To build the sources on Unix-based systems, run: + +```sh +./build/build.sh +``` + +On Windows, run: + +```sh +.\build\build.bat +``` + +After the build process completes, you will find the `jf` or `jf.exe` executable in the current directory. + +### Dependencies in other JFrog modules + +This project heavily depends on the following modules: + +- [github.com/jfrog/jfrog-client-go](https://github.com/jfrog/jfrog-client-go) +- [github.com/jfrog/jfrog-cli-core](github.com/jfrog/jfrog-cli-core) +- [github.com/jfrog/build-info-go](github.com/jfrog/build-info-go) +- [github.com/jfrog/gofrog](github.com/jfrog/gofrog) + +#### Local Development + +During local development, if you come across code that needs to be modified in one of the mentioned modules, it is advisable to replace the dependency with a local clone of the module. + +For instance, let's assume you wish to modify files from `jfrog-cli-core`. Clone the `jfrog-cli-core` repository (preferably your fork) to your local development machine, placing it at `/local/path/in/your/machine/jfrog-cli-core`. + +To include this local dependency, modify the `go.mod` file as follows: + +``` +replace github.com/jfrog/jfrog-cli-core/v2 => /local/path/in/your/machine/jfrog-cli-core +``` + +Afterward, execute `go mod tidy` to ensure the Go module files are updated. Note that Go will automatically adjust the version in the `go.mod` file. + +#### Pull Requests + +Once you have completed your coding changes, it is recommended to push the modifications made to the other modules first. Once these changes are pushed, you can update this project to resolve dependencies from your GitHub fork or branch. To achieve this, modify the `go.mod` file to point the dependency to your repository and branch, as shown in the example below: + +``` +replace github.com/jfrog/jfrog-cli-core/v2 => github.com/galusben/jfrog-cli-core/v2 dev +``` + +Finally, execute `go mod tidy` to update the Go module files. Please note that Go will automatically update the version in the `go.mod` file. + +## Tests + +### Usage + +To run tests, use the following command: + +``` +go test -v github.com/jfrog/jfrog-cli [test-types] [flags] +``` + +The available flags are: + +| Flag | Description | +| ------------------- | ----------------------------------------------------------------------------------------------- | +| `-jfrog.url` | [Default: http://localhost:8081] JFrog platform URL | +| `-jfrog.user` | [Default: admin] JFrog platform username | +| `-jfrog.password` | [Default: password] JFrog platform password | +| `-jfrog.adminToken` | [Optional] JFrog platform admin token | +| `-ci.runId` | [Optional] A unique identifier used as a suffix to create repositories and builds in the tests. | + +The available test types are: + +| Type | Description | +| -------------------- | ------------------ | +| `-test.artifactory` | Artifactory tests | +| `-test.access` | Access tests | +| `-test.npm` | Npm tests | +| `-test.maven` | Maven tests | +| `-test.gradle` | Gradle tests | +| `-test.docker` | Docker tests | +| `-test.dockerScan` | Docker scan tests | +| `-test.podman` | Podman tests | +| `-test.go` | Go tests | +| `-test.pip` | Pip tests | +| `-test.pipenv` | Pipenv tests | +| `-test.poetry` | Poetry tests | +| `-test.nuget` | Nuget tests | +| `-test.plugins` | Plugins tests | +| `-test.distribution` | Distribution tests | +| `-test.transfer` | Transfer tests | +| `-test.xray` | Xray tests | + +When running the tests, builds and repositories with timestamps will be created, for example: `cli-rt1-1592990748` and `cli-rt2-1592990748`. The content of these repositories will be deleted once the tests are completed. + +#### Artifactory tests + +In addition to the [general optional flags](#Usage), you can use the following optional Artifactory flags: + +| Flag | Description | +| ---------------------- | --------------------------------------------------------------------------------------------------------------- | +| `-jfrog.sshKeyPath` | [Optional] Path to the SSH key file. Use this flag only if the Artifactory URL format is `ssh://[domain]:port`. | +| `-jfrog.sshPassphrase` | [Optional] Passphrase for the SSH key. | + +##### Examples + +To run Artifactory tests, execute the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.artifactory [flags] +``` + +#### Npm tests + +##### Requirements + +- The _npm_ executables should be included in the system's `PATH` environment variable. +- The tests are compatible with npm 7 and higher. + +##### Limitations + +- Currently, npm integration only supports HTTP(S) connections to Artifactory using username and password. + +##### Examples + +To run Npm tests, execute the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.npm [flags] +``` + +#### Maven tests + +##### Requirements + +- The _java_ executable should be included in the system's `PATH` environment variable. Alternatively, set the `_JAVA_HOME` environment variable. + +##### Limitations + +- Currently, Maven integration only supports HTTP(S) connections to Artifactory using username and password. + +##### Examples + +To run Maven tests, execute the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.maven [flags] +``` + +#### Gradle tests + +##### Requirements + +- The _gradle_ and _java_ executables should be included in the system's `PATH` environment variable. Alternatively, set the `JAVA_HOME` environment variable. + +##### Limitations + +- Currently, Gradle integration only supports HTTP(S) connections to Artifactory using username and password. + +##### Examples + +To run Gradle tests, execute the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.gradle [flags] +``` + +#### Docker tests + +##### Requirements + +- Make sure the `RTLIC` environment variable is configured with a valid license. +- You can start an Artifactory container by running the `startArtifactory.sh` script located in the `testdata/docker/artifactory` directory. Before running the tests, wait for Artifactory to finish booting up in the container. + +| Flag | Description | +| ------------------------- | ----------------------------------- | +| `-test.containerRegistry` | Artifactory Docker registry domain. | + +##### Examples + +To run Docker tests, execute the following command (replace the missing parameters as described below): + +``` +go test -v github.com/jfrog/jfrog-cli -test.docker [flags] +``` + +#### Podman tests + +| Flag | Description | +| ------------------------- | -------------------------------------- | +| `-test.containerRegistry` | Artifactory container registry domain. | + +##### Examples + +To run Podman tests, execute the following command (replace the missing parameters as described below): + +``` +go test -v github.com/jfrog/jfrog-cli -test.podman [flags] +``` + +#### Go commands tests + +##### + +Requirements + +- The tests are compatible with Artifactory 6.10 and higher. +- To run Go tests, use the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.go [flags] +``` + +#### NuGet tests + +##### Requirements + +- Add the NuGet executable to the system's `PATH` environment variable. +- Run the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.nuget [flags] +``` + +#### Pip tests + +##### Requirements + +- Add the Python and pip executables to the system's `PATH` environment variable. +- Run the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.pip [flags] +``` + +#### Plugins tests + +To run Plugins tests, execute the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.plugins +``` + +#### Distribution tests + +To run Distribution tests, execute the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.distribution [flags] +``` + +#### Transfer tests + +##### Requirement + +The Transfer tests execute `transfer-files` commands between a local Artifactory server and a remote SaaS instance. In addition to the [general optional flags](#Usage), you _must_ use the following flags: + +| Flag | Description | +| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `-jfrog.targetUrl` | JFrog target platform URL. | +| `-jfrog.targetAdminToken` | JFrog target platform admin token. | +| `-jfrog.jfrogHome` | The JFrog home directory of the local Artifactory installation. | +| `-jfrog.installDataTransferPlugin` | Set this flag to `true` if you want the test to automatically install the data-transfer plugin in the source Artifactory server. | + +To run Transfer tests, execute the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.transfer [flags] +``` + +### Xray tests + +To run Xray tests, execute the following command: + +``` +go test -v github.com/jfrog/jfrog-cli -test.xray -test.dockerScan [flags] +``` diff --git a/README.md b/README.md index c6112be75..16955cb4e 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,7 @@ [![Go Report Card](https://goreportcard.com/badge/github.com/jfrog/jfrog-cli)](https://goreportcard.com/report/github.com/jfrog/jfrog-cli) [![license](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=flat)](https://raw.githubusercontent.com/jfrog/jfrog-cli/v2/LICENSE) [![](https://img.shields.io/badge/Docs-%F0%9F%93%96-blue)](https://www.jfrog.com/confluence/display/CLI/JFrog+CLI) [![Go version](https://img.shields.io/github/go-mod/go-version/jfrog/jfrog-cli)](https://tip.golang.org/doc/go1.20) +
@@ -235,8 +236,6 @@ - [Overview](#overview) - [Download and Installation](#download-and-installation) -- [Building the Executable](#building-the-executable) -- [Tests](#tests) - [Code Contributions](#code-contributions) - [Using JFrog CLI](#using-jfrog-cli) - [JFrog CLI Plugins](#jfrog-cli-plugins) @@ -260,325 +259,9 @@ Several features of the JFrog CLI makes your scripts more efficient and reliable You can either install JFrog CLI using one of the supported installers or download its executable directly. Visit the [Install JFrog CLI Page](https://jfrog.com/getcli/) for details. -# Building the Executable - -JFrog CLI is written in the [Go programming language](https://golang.org/), so to build the CLI yourself, you first need -to have Go installed and configured on your machine. - -## Install Go - -To download and install `Go`, please refer to the [Go documentation](https://golang.org/doc/install). -Please download `Go 1.14.x` or above. - -## Download and Build the CLI - -Navigate to a directory where you want to create the jfrog-cli project, **outside** the `$GOPATH` tree. - -If the `GOPATH` variable is unset, it's default value is the go folder under the user home. - -Verify that the `GO111MODULE` variable is either unset, or explicitly set to `auto`. - -Clone the jfrog-cli project by executing the following command: - -``` -git clone https://github.com/jfrog/jfrog-cli -``` - -Build the project by navigating to the jfrog folder and executing the following commands. -On Unix based systems run: - -``` -cd jfrog-cli -build/build.sh -``` - -On Windows run: - -``` -cd jfrog-cli -build\build.bat -``` - -Once completed, you will find the JFrog CLI executable at your current directory. - -# Tests - -### Usage - -``` -go test -v github.com/jfrog/jfrog-cli [test-types] [flags] -``` - -The flags are: - -| Flag | Description | -|---------------------|-------------------------------------------------------------------------------------------------| -| `-jfrog.url` | [Default: http://localhost:8081] JFrog platform URL. | -| `-jfrog.user` | [Default: admin] JFrog platform username. | -| `-jfrog.password` | [Default: password] JFrog platform password. | -| `-jfrog.adminToken` | [Optional] JFrog platform admin token. | -| `-ci.runId` | [Optional] A unique identifier used as a suffix to create repositories and builds in the tests. | - -The types are: - -| Type | Description | -|----------------------|--------------------| -| `-test.artifactory` | Artifactory tests | -| `-test.access` | Access tests | -| `-test.npm` | Npm tests | -| `-test.maven` | Maven tests | -| `-test.gradle` | Gradle tests | -| `-test.docker` | Docker tests | -| `-test.dockerScan` | Docker scan tests | -| `-test.podman` | Podman tests | -| `-test.go` | Go tests | -| `-test.pip` | Pip tests | -| `-test.pipenv` | Pipenv tests | -| `-test.poetry` | Poetry tests | -| `-test.nuget` | Nuget tests | -| `-test.plugins` | Plugins tests | -| `-test.distribution` | Distribution tests | -| `-test.transfer` | Transfer tests | -| `-test.xray` | Xray tests | - -- Running the tests will create builds and repositories with timestamps, - for example: `cli-rt1-1592990748` and `cli-rt2-1592990748`.
- Once the tests are completed, the content of these repositories will be deleted. - -#### Artifactory tests - -In addition to [general optional flags](#Usage) you can use the following optional artifactory flags. - -| Flag | Description | -|------------------------|---------------------------------------------------------------------------------------------------------| -| `-jfrog.sshKeyPath` | [Optional] Ssh key file path. Should be used only if the Artifactory URL format is ssh://[domain]:port. | -| `-jfrog.sshPassphrase` | [Optional] Ssh key passphrase. | - -##### Examples - -To run artifactory tests execute the following command. - -``` -go test -v github.com/jfrog/jfrog-cli -test.artifactory [flags] -``` - -#### Npm tests - -##### Requirements - -- The _npm_ executables should be included as part of the _PATH_ environment variable. -- The tests are compatible with npm 7 and higher. - -##### Limitation - -- Currently, npm integration support only http(s) connections to Artifactory using username and password. - -##### Examples - -To run npm tests execute the following command. - -``` -go test -v github.com/jfrog/jfrog-cli -test.npm [flags] -``` - -#### Maven tests - -##### Requirements - -- The _java_ executable should be included as part of the _PATH_ environment variable. Alternatively, set the - _JAVA_HOME_ environment variable. - -##### Limitation - -- Currently, maven integration support only http(s) connections to Artifactory using username and password. - -##### Examples - -To run maven tests execute the following command. - -``` -go test -v github.com/jfrog/jfrog-cli -test.maven [flags] -``` - -#### Gradle tests - -##### Requirements - -- The _gradle_ executables should be included as part of the _PATH_ environment variable. -- The _java_ executable should be included as part of the _PATH_ environment variable. Alternatively, set the - _JAVA_HOME_ environment variable. - -##### Limitation - -- Currently, gradle integration support only http(s) connections to Artifactory using username and password. - -##### Examples - -To run gradle tests execute the following command. - -``` -go test -v github.com/jfrog/jfrog-cli -test.gradle [flags] -``` - -#### Docker tests - -##### Requirements - -- Make sure the environment variable `RTLIC` is configured with a valid license. -- You can start an Artifactory container by running the `startArtifactory.sh` script under - the `testdata/docker/artifactory` directory. Before running the tests, wait for Artifactory to finish booting up in - the container. - -| Flag | Description | -|---------------------------|-------------------------------------| -| `-test.containerRegistry` | Artifactory Docker registry domain. | - -##### Examples - -To run docker tests execute the following command (fill out the missing parameters as described below). - -``` -go test -v github.com/jfrog/jfrog-cli -test.docker [flags] -``` - -#### Podman tests - -| Flag | Description | -|---------------------------|----------------------------------------| -| `-test.containerRegistry` | Artifactory container registry domain. | - -##### Examples - -To run podman tests execute the following command (fill out the missing parameters as described below). - -``` -go test -v github.com/jfrog/jfrog-cli -test.podman [flags] -``` - -#### Go commands tests - -##### Requirements - -- The tests are compatible with Artifactory 6.10 and higher. -- To run go tests run the following command: - -``` -go test -v github.com/jfrog/jfrog-cli -test.go [flags] -``` - -#### NuGet tests - -##### Requirements - -- Add NuGet executable to the system search path (PATH environment variable). -- Run the following command: - -``` -go test -v github.com/jfrog/jfrog-cli -test.nuget [flags] -``` - -#### Pip tests - -##### Requirements - -- Add Python and pip executables to the system search path (PATH environment variable). -- Run the following command: - -``` -go test -v github.com/jfrog/jfrog-cli -test.pip [flags] -``` - -#### Plugins tests - -To run Plugins tests execute the following command: - -``` -go test -v github.com/jfrog/jfrog-cli -test.plugins -``` - -### Distribution tests - -To run Distribution tests execute the following command: - -``` -go test -v github.com/jfrog/jfrog-cli -test.distribution [flags] -``` - -### Transfer tests - -##### Requirement - -The transfer tests execute `transfer-files` commands between a local Artifactory server and a remote SaaS instance. -In addition to [general optional flags](#Usage) you _must_ use the following flags: - -| Flag | Description | -|------------------------------------|----------------------------------------------------------------------------------------------------------------| -| `-jfrog.targetUrl` | JFrog target platform URL. | -| `-jfrog.targetAdminToken` | JFrog target platform admin token. | -| `-jfrog.jfrogHome` | The JFrog home directory of the local Artifactory installation. | -| `-jfrog.installDataTransferPlugin` | Set to true if you'd like the test to install the data-transfer automatically in the source Artifactory server | - -To run transfer tests execute the following command: - -``` -go test -v github.com/jfrog/jfrog-cli -test.transfer [flags] -``` - -### Xray tests - -To run Xray tests execute the following command: - -``` -go test -v github.com/jfrog/jfrog-cli -test.xray -test.dockerScan [flags] -``` - # Code Contributions -We welcome code contributions through pull requests from the community. - -## Pull Requests Guidelines - -- If the existing tests do not already cover your changes, please add tests.. -- Pull requests should be created on the _dev_ branch. -- Please use [gofmt](https://golang.org/cmd/gofmt/) for formatting the code before submitting the pull request. - -## Dependencies in other JFrog modules - -This project heavily depends on: - -- github.com/jfrog/jfrog-client-go -- github.com/jfrog/build-info-go -- github.com/jfrog/jfrog-cli-core - -### Local Development - -During local development, when you encounter code that needs to be changed from one of the above modules, it is -recommended to replace the dependency to work with a local clone of the dependency. - -For example, assuming you would like to change files from jfrog-cli-core. -Clone jfrog-cli-core (preferably your fork) to your local development machine -(assuming it will be cloned to `/repos/jfrog-cli-core`). - -Change go.mod to include the following: - -``` -replace github.com/jfrog/jfrog-cli-core/v2 => /repos/jfrog-cli-core -``` - -### Pull Requests - -Once done with your coding, you should push the changes you made to the other modules first. Once pushed, you can change -this -project to resolve the dependencies from your GitHub fork / branch. -This is done by pointing the dependency in go.mod to your repository and branch. For example: - -``` -replace github.com/jfrog/jfrog-cli-core/v2 => github.com/galusben/jfrog-cli-core/v2 dev -``` - -Then run `go mod tidy` - -Notice that go will change the version in the go.mod file. +We welcome pull requests from the community. To help us improve this project, please read our [contribution](CONTRIBUTING.md) guide. # Using JFrog CLI