github.com/Thanhphan1147/cloudfoundry-cli@v7.1.0+incompatible/.github/CONTRIBUTING.md (about) 1 # Contributing to CLI 2 3 The Cloud Foundry team uses GitHub and accepts code contributions via [pull 4 requests](https://help.github.com/articles/about-pull-requests/). 5 6 ## CLI v6.x & v7-beta 7 8 The code base is undergoing major work to support new Cloud Controller APIs. 9 Most CLI users have a v6 CLI. 10 Some users are trying out a beta version of v7. 11 Both versions are in active development. 12 You will find the entry point for v6 commands in the _cli/command/v6_ directory. 13 v7 commands are found in the _cli/command/v7_ directory. 14 More details are available in the [Architecture Guide](https://github.com/cloudfoundry/cli/wiki/Architecture-Guide). 15 16 **Note**: The CLI can currently be compiled to use V6 or V7 code paths. 17 Depending on the nature of the intended changes, you may be contributing to V6 18 code, V7 code, and/or shared code. The rest of this guide assumes that 19 your changes are to V6 code or shared code. If your changes are in V7 code, refer to the 20 [V7-specific contributing information](https://github.com/cloudfoundry/cli/wiki/Contributing-V7.md) for more information. 21 If your changes are to shared code, please also run V7 tests before submitting a 22 pull request. 23 24 The `make` commands in this file can be used with V6 or V7 code. To run the V7 25 version of tests or build the V7 version of the binary, set `TARGET_V7=1` in the 26 environment. If `TARGET_V7` is unset, `make` commands will target V6. 27 28 ## Prerequisites 29 30 Before working on a PR to the CLI code base, please: 31 32 - reach out to us first via a [GitHub issue](https://github.com/cloudfoundry/cli/issues), 33 - look for the [contributions welcome label on GitHub](https://github.com/cloudfoundry/cli/issues?q=is%3Aopen+is%3Aissue+label%3A%22contributions+welcome%22) 34 for issues we are actively looking for help on. 35 36 You can always chat with us on our [Slack #cli channel](https://cloudfoundry.slack.com) ([request an invite](http://slack.cloudfoundry.org/)), 37 38 After reaching out to the CLI team and the conclusion is to make a PR, please follow these steps: 39 40 1. Ensure that you have either: 41 * completed our [Contributor License Agreement (CLA) for individuals](https://www.cloudfoundry.org/pdfs/CFF_Individual_CLA.pdf), 42 * or, are a [public member](https://help.github.com/articles/publicizing-or-hiding-organization-membership/) of an organization 43 that has signed [the corporate CLA](https://www.cloudfoundry.org/pdfs/CFF_Corporate_CLA.pdf). 44 1. Review the CF CLI [Style Guide](https://github.com/cloudfoundry/cli/wiki/CF-CLI-Style-Guide), 45 [Architecture Guide](https://github.com/cloudfoundry/cli/wiki/Architecture-Guide), 46 [Code Style Guide](https://github.com/cloudfoundry/cli/wiki/Code-Style-Guide), 47 [Testing Style Guide](https://github.com/cloudfoundry/cli/wiki/Testing-Style-Guide), 48 or [Internationalization Guide](https://github.com/cloudfoundry/cli/wiki/Internationalization-Guide). 49 1. Fork the project repository. 50 1. Create a feature branch (e.g. `git checkout -b better_cli`) and make changes on this branch 51 * Follow the other sections on this page to [set up your development environment](#development-environment-setup), [build `cf`](#building-the-cf-binary) and [run the tests](#testing). 52 * Tests are required for any changes. 53 1. Push to your fork (e.g. `git push origin better_cli`) and [submit a pull request](https://help.github.com/articles/creating-a-pull-request) 54 55 Note: All contributions must be sent using GitHub Pull Requests. 56 We prefer a small, focused pull request with a clear message 57 that conveys the intent of your change. 58 59 # Development Environment Setup 60 61 ## Install Golang 1.13 62 63 Documentation on installing GoLang can be found [here](https://golang.org/doc/install). While 64 the CF CLI might be compatible with other versions of GoLang, this is the only 65 version that the `cli` binary is built and tested with. 66 67 ## Development tools 68 69 The CF CLI requires the following development tools in order to run our test: 70 - [Ginkgo](https://github.com/onsi/ginkgo) / [Gomega](https://github.com/onsi/gomega) - Test framework/Matchers Library 71 - [golangci-lint](https://github.com/golangci/golangci-lint) - Comprehensive linting tool 72 - [counterfeiter](https://github.com/maxbrunsfeld/counterfeiter) - Generate 73 fakes/mocks for testing. Currently using version `6.*`. 74 - [dep](https://github.com/golang/dep) - `vendor` dependency management tool 75 - [make](https://www.gnu.org/software/make/) - tool for building the CLI and 76 running it's tests. 77 78 ## Git Checkout 79 80 The CF CLI should **not** be checked out under `src/github.com`, instead it 81 should be checked out under `src/code.cloudfoundry.org`. While they resolve to 82 the same thing on checkout, GoLang will be unable to _correctly_ resolve them at 83 build time. 84 85 ```bash 86 mkdir -p $GOPATH/src/code.cloudfoundry.org 87 cd $GOPATH/src/code.cloudfoundry.org 88 git clone https://github.com/cloudfoundry/cli.git 89 ``` 90 91 # Building the `cf` binary 92 93 Build the binary for the **current architecture** and adding it to the `PATH`: 94 ```bash 95 cd $GOPATH/src/code.cloudfoundry.org/cli 96 make build 97 export PATH=$GOPATH/src/code.cloudfoundry.org/cli/out:$PATH # Puts the built CLI first in your PATH 98 ``` 99 100 ### Compiling for Other Operating Systems and Architectures 101 102 The supported platforms for the CF CLI are Linux (32-bit and 64-bit), Windows 103 (32-bit and 64-bit) and OSX (aka Darwin). The commands that build the binaries 104 can be seen in the [Makefile](/Makefile) where the target begins with the 105 `out/cf-cli`. 106 107 108 For general information on how to cross compile GoLang binaries, see the [Go 109 environment variables 110 documentation](https://golang.org/doc/install/source#environment) for details on 111 how to cross compile binaries for other architectures. 112 113 # Testing 114 115 ## Running the Unit tests 116 117 To run the unit tests: 118 ```bash 119 cd $GOPATH/src/code.cloudfoundry.org/cli 120 make units-full # will run all unit tests 121 make units # runs all non-cf directory unit tests 122 ``` 123 124 **Note: `make units-full` is recommended over `make units` if you are unsure of 125 how wide reaching the intended changes are.** 126 127 ## Running the Integration tests 128 129 The [Integration test README](/integration/README.md) contains a full set of 130 details on how to configure and run the integration tests. In addition to the 131 configuration mentioned in the README, the CLI's `Makefile` contains the 132 following support commands that will run `make build integration-cleanup` prior 133 to running integration tests: 134 135 ```bash 136 make integration-experimental # runs the experimental integration tests 137 make integration-global # runs the global integration tests 138 make integration-isolated # runs the isolated integration tests 139 make integration-plugin # runs the plugin integration tests 140 make integration-push # runs the push integration tests 141 make integration-tests # runs the isolated, push and global integration tests 142 make integration-tests-full # runs all the integration suites 143 ``` 144 145 If the number of parallel nodes for the non-global test suites would like to be 146 adjusted, set the `NODES` environment variable: 147 148 ```bash 149 NODES=10 make integration-tests 150 ``` 151 152 # Modifying the CLI codebase 153 154 All changes to the CF CLI require updates to the unit/integration test. There 155 are additional requirements around updating the CF CLI that will be listed 156 below. 157 158 ## Updating counterfeiter fakes 159 160 The CLI uses [`counterfeiter`](https://github.com/maxbrunsfeld/counterfeiter) to 161 generate fakes from interfaces for the unit tests. If any changes are made to an 162 interface, the fakes be should regenerated using counterfeiter: 163 164 ```bash 165 go generate ./<package>/... 166 ``` 167 168 where `<package>` contains the package with the changed interface. 169 170 ### Notes 171 1. `counterfeiter` fakes should never be manually edited. They are only 172 created/modified via `go generate`. **All pull requests with manually modified 173 fakes will be rejected.** 174 1. Do not run `go generate` from the root directory. Fakes in the legacy 175 codebase require additional intervention so it preferred not to modify them 176 unless it is _absolutely_ necessary. 177 178 ## Vendoring Dependencies 179 180 The CLI uses [`dep`](https://github.com/golang/dep) to manage vendored 181 dependencies. Refer to the [`dep` 182 documentation](https://golang.github.io/dep/docs/daily-dep.html) for managing 183 dependencies. 184 185 If you are vendoring a new dependency, please read [License and Notice 186 Files](https://github.com/cloudfoundry/cli/wiki/License-and-Notice-Files) to 187 abide by third party licenses. 188 189 ## API Versioning 190 191 The CLI has a minimum version requirements for the APIs it interfaces with, the 192 requirements for these APIs are listed in the [Version Policy 193 guide](https://github.com/cloudfoundry/cli/wiki/Versioning-Policy#cf-cli-minimum-supported-version). 194 195 If your pull request requires a CAPI version higher than the minimum API version, 196 the CLI code and integration tests must be versioned tests. This new 197 functionality has the following requirements: 198 199 1. The minimum version is added to the [Minimum API version 200 list](/api/cloudcontroller/ccversion/minimum_version.go). 201 1. The feature has an appropriate version check in the `command` layer to prevent 202 use of that feature if the targeted API is below the minimum version. **Note: 203 commands should FAIL prior to execution when minimum version is not met for 204 specified functionality.** 205 1. The integration tests that are added use the `helpers.SkipIfVersionLessThan` 206 or `helpers.SkipIfVersionGreaterThan` helpers in their `BeforeEach`. See this 207 [example](https://github.com/cloudfoundry/cli/blob/87aaed8215fad3b2077c6829d1812ead3902d5cf/integration/isolated/create_isolation_segment_command_test.go#L17).