cli/.github/CONTRIBUTING.md at master

The Cloud Foundry team uses GitHub and accepts code contributions via pull requests.

CLI v6.x & v7-beta

The code base is undergoing major work to support new Cloud Controller APIs. Most CLI users have a v6 CLI. Some users are trying out a beta version of v7. Both versions are in active development. You will find the entry point for v6 commands in the cli/command/v6 directory. v7 commands are found in the cli/command/v7 directory. More details are available in the Architecture Guide.

Note: The CLI can currently be compiled to use V6 or V7 code paths. Depending on the nature of the intended changes, you may be contributing to V6 code, V7 code, and/or shared code. The rest of this guide assumes that your changes are to V6 code or shared code. If your changes are in V7 code, refer to the V7-specific contributing information for more information. If your changes are to shared code, please also run V7 tests before submitting a pull request.

The make commands in this file can be used with V6 or V7 code. To run the V7 version of tests or build the V7 version of the binary, set TARGET_V7=1 in the environment. If TARGET_V7 is unset, make commands will target V6.

Prerequisites

Before working on a PR to the CLI code base, please:

reach out to us first via a GitHub issue,
look for the contributions welcome label on GitHub for issues we are actively looking for help on.

You can always chat with us on our Slack #cli channel (request an invite),

After reaching out to the CLI team and the conclusion is to make a PR, please follow these steps:

Ensure that you have either:
- completed our Contributor License Agreement (CLA) for individuals,
- or, are a public member of an organization that has signed the corporate CLA.
Review the CF CLI Style Guide, Architecture Guide, Code Style Guide, Testing Style Guide, or Internationalization Guide.
Fork the project repository.
Create a feature branch (e.g. git checkout -b better_cli) and make changes on this branch
- Follow the other sections on this page to set up your development environment, build cf and run the tests.
- Tests are required for any changes.
Push to your fork (e.g. git push origin better_cli) and submit a pull request

Note: All contributions must be sent using GitHub Pull Requests. We prefer a small, focused pull request with a clear message that conveys the intent of your change.

Development Environment Setup

Install Golang 1.12

Documentation on installing GoLang can be found here. While the CF CLI might be compatible with other versions of GoLang, this is the only version that the cli binary is built and tested with.

Development tools

The CF CLI requires the following development tools in order to run our test:

Ginkgo / Gomega - Test framework/Matchers Library
golangci-lint - Comprehensive linting tool
counterfeiter - Generate fakes/mocks for testing. Currently using version 6.*.
dep - vendor dependency management tool
make - tool for building the CLI and running it's tests.

Git Checkout

The CF CLI should not be checked out under src/github.com, instead it should be checked out under src/code.cloudfoundry.org. While they resolve to the same thing on checkout, GoLang will be unable to correctly resolve them at build time.

mkdir -p $GOPATH/src/code.cloudfoundry.org
cd $GOPATH/src/code.cloudfoundry.org
git clone https://github.com/cloudfoundry/cli.git

Building the `cf` binary

Build the binary for the current architecture and adding it to the PATH:

cd $GOPATH/src/code.cloudfoundry.org/cli
make build
export PATH=$GOPATH/src/code.cloudfoundry.org/cli/out:$PATH # Puts the built CLI first in your PATH

Compiling for Other Operating Systems and Architectures

The supported platforms for the CF CLI are Linux (32-bit and 64-bit), Windows (32-bit and 64-bit) and OSX (aka Darwin). The commands that build the binaries can be seen in the Makefile where the target begins with the out/cf-cli.

For general information on how to cross compile GoLang binaries, see the Go environment variables documentation for details on how to cross compile binaries for other architectures.

Testing

Running the Unit tests

To run the unit tests:

cd $GOPATH/src/code.cloudfoundry.org/cli
make units-full # will run all unit tests
make units # runs all non-cf directory unit tests

Note: make units-full is recommended over make units if you are unsure of how wide reaching the intended changes are.

Running the Integration tests

The Integration test README contains a full set of details on how to configure and run the integration tests. In addition to the configuration mentioned in the README, the CLI's Makefile contains the following support commands that will run make build integration-cleanup prior to running integration tests:

make integration-experimental # runs the experimental integration tests
make integration-global # runs the global integration tests
make integration-isolated # runs the isolated integration tests
make integration-plugin # runs the plugin integration tests
make integration-push # runs the push integration tests
make integration-tests # runs the isolated, push and global integration tests
make integration-tests-full # runs all the integration suites

If the number of parallel nodes for the non-global test suites would like to be adjusted, set the NODES environment variable:

NODES=10 make integration-tests

Modifying the CLI codebase

All changes to the CF CLI require updates to the unit/integration test. There are additional requirements around updating the CF CLI that will be listed below.

Updating counterfeiter fakes

The CLI uses counterfeiter to generate fakes from interfaces for the unit tests. If any changes are made to an interface, the fakes be should regenerated using counterfeiter:

go generate ./<package>/...

where <package> contains the package with the changed interface.

Notes

counterfeiter fakes should never be manually edited. They are only created/modified via go generate. All pull requests with manually modified fakes will be rejected.
Do not run go generate from the root directory. Fakes in the legacy codebase require additional intervention so it preferred not to modify them unless it is absolutely necessary.

Vendoring Dependencies

The CLI uses dep to manage vendored dependencies. Refer to the dep documentation for managing dependencies.

If you are vendoring a new dependency, please read License and Notice Files to abide by third party licenses.

API Versioning

The CLI has a minimum version requirements for the APIs it interfaces with, the requirements for these APIs are listed in the Version Policy guide.

If your pull request requires a CAPI version higher than the minimum API version, the CLI code and integration tests must be versioned tests. This new functionality has the following requirements:

The minimum version is added to the Minimum API version list.
The feature has an appropriate version check in the command layer to prevent use of that feature if the targeted API is below the minimum version. Note: commands should FAIL prior to execution when minimum version is not met for specified functionality.
The integration tests that are added use the helpers.SkipIfVersionLessThan or helpers.SkipIfVersionGreaterThan helpers in their BeforeEach. See this example.