The Cloud Foundry team uses GitHub and accepts code contributions via pull requests.
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.
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.
- Follow the other sections on this page to set up your development environment, build
- 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.
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.
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.
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
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
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.
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.
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
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.
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.
counterfeiter
fakes should never be manually edited. They are only created/modified viago 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.
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.
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
orhelpers.SkipIfVersionGreaterThan
helpers in theirBeforeEach
. See this example.