hub.fastgit.org/hashicorp/consul.git@v1.4.5/.github/CONTRIBUTING.md (about)

     1  # Contributing to Consul
     2  >**Note:** We take Consul's security and our users' trust very seriously.
     3  >If you believe you have found a security issue in Consul, please responsibly
     4  >disclose by contacting us at security@hashicorp.com.
     5  
     6  **First:** if you're unsure or afraid of _anything_, just ask or submit the
     7  issue or pull request anyways. You won't be yelled at for giving your best
     8  effort. The worst that can happen is that you'll be politely asked to change
     9  something. We appreciate any sort of contributions, and don't want a wall of
    10  rules to get in the way of that.
    11  
    12  That said, if you want to ensure that a pull request is likely to be merged, 
    13  talk to us! A great way to do this is in issues themselves. When you want to 
    14  work on an issue, comment on it first and tell us the approach you want to take.
    15  
    16  ## Getting Started
    17  ### Some Ways to Contribute
    18  * Report potential bugs.
    19  * Suggest product enhancements.
    20  * Increase our test coverage.
    21  * Fix a [bug](https://github.com/hashicorp/consul/labels/bug).
    22  * Implement a requested [enhancement](https://github.com/hashicorp/consul/labels/enhancement).
    23  * Improve our guides and documentation. Consul's [Guides](https://www.consul.io/docs/guides/index.html), [Docs](https://www.consul.io/docs/index.html), and [api godoc](https://godoc.org/github.com/hashicorp/consul/api)
    24  are deployed from this repo.
    25  * Respond to questions about usage on the issue tracker or mailing list.
    26  
    27  ### Reporting an Issue:
    28  >Note: Issues on GitHub for Consul are intended to be related to bugs or feature requests. 
    29  >Questions should be directed to other community resources such as the: [Mailing List](https://groups.google.com/group/consul-tool/), [FAQ](https://www.consul.io/docs/faq.html), or [Guides](https://www.consul.io/docs/guides/index.html).
    30  
    31  * Make sure you test against the latest released version. It is possible we 
    32  already fixed the bug you're experiencing. However, if you are on an older 
    33  version of Consul and feel the issue is critical, do let us know.
    34  
    35  * Check existing issues (both open and closed) to make sure it has not been 
    36  reported previously.
    37  
    38  * Provide a reproducible test case. If a contributor can't reproduce an issue, 
    39  then it dramatically lowers the chances it'll get fixed.
    40  
    41  * Aim to respond promptly to any questions made by the Consul team on your 
    42  issue. Stale issues will be closed.
    43  
    44  ### Issue Lifecycle
    45  
    46  1. The issue is reported.
    47  
    48  2. The issue is verified and categorized by a Consul maintainer.
    49     Categorization is done via tags. For example, bugs are tagged as "bug".
    50  
    51  3. Unless it is critical, the issue is left for a period of time (sometimes many
    52     weeks), giving outside contributors a chance to address the issue.
    53  
    54  4. The issue is addressed in a pull request or commit. The issue will be
    55     referenced in the commit message so that the code that fixes it is clearly
    56     linked.
    57  
    58  5. The issue is closed.
    59  
    60  ## Building Consul
    61  
    62  If you wish to work on Consul itself, you'll first need [Go](https://golang.org)
    63  installed (version 1.10+ is _required_). Make sure you have Go properly installed,
    64  including setting up your [GOPATH](https://golang.org/doc/code.html#GOPATH).
    65  
    66  Next, clone this repository into `$GOPATH/src/github.com/hashicorp/consul` and 
    67  then run `make dev`. In a few moments, you'll have a working `consul` executable 
    68  in `consul/bin` and `$GOPATH/bin`:
    69  
    70  >Note: `make dev` will build for your local machine's os/architecture. If you wish to build for all os/architecture combinations use `make`.
    71  
    72  ## Making Changes to Consul
    73  
    74  The first step to making changes is to fork Consul. Afterwards, the easiest way 
    75  to work on the fork is to set it as a remote of the Consul project:
    76  
    77  1. Navigate to `$GOPATH/src/github.com/hashicorp/consul`
    78  2. Rename the existing remote's name: `git remote rename origin upstream`.
    79  3. Add your fork as a remote by running
    80     `git remote add origin <github url of fork>`. For example:
    81     `git remote add origin https://github.com/myusername/consul`.
    82  4. Checkout a feature branch: `git checkout -t -b new-feature`
    83  5. Make changes
    84  6. Push changes to the fork when ready to submit PR:
    85     `git push -u origin new-feature`
    86  
    87  By following these steps you can push to your fork to create a PR, but the code on disk still
    88  lives in the spot where the go cli tools are expecting to find it.
    89  
    90  >Note: If you make any changes to the code, run `make format` to automatically format the code according to Go standards.
    91  
    92  ## Testing
    93  
    94  Before submitting changes, run **all** tests locally by typing `make test`. 
    95  The test suite may fail if over-parallelized, so if you are seeing stochastic 
    96  failures try `GOTEST_FLAGS="-p 2 -parallel 2" make test`. 
    97  
    98  Certain testing patterns such as creating a test `Client` in the `api` pkg 
    99  or a `TestAgent` followed by a session can lead to flaky tests. More generally, 
   100  any tests with components that rely on readiness of other components are often
   101  flaky. 
   102  
   103  Our makefile has some tooling built in to help validate the stability of single 
   104  or package-wide tests. By running the `test-flake` goal we spin up a local docker 
   105  container that mirrors a CPU constrained version of our CI environment. Here we can 
   106  surface uncommon failures that are typically hard to reproduce by re-running 
   107  tests multiple times. 
   108  
   109  The makefile goal accepts the following variables as arguments:
   110  
   111  * **FLAKE_PKG** Target package (required)
   112  
   113  * **FLAKE_TEST** Target test
   114  
   115  * **FLAKE_CPUS** Amount of CPU resources for container
   116  
   117  * **FLAKE_N** Number of times to run tests
   118  
   119  Examples:
   120  `make test-flake FLAKE_PKG=connect/proxy`
   121  `make test-flake FLAKE_PKG=connect/proxy FLAKE_TEST=TestUpstreamListener`
   122  `make test-flake FLAKE_PKG=connect/proxy FLAKE_TEST=TestUpstreamListener FLAKE_CPUS=0.15 FLAKE_N=30`
   123  
   124  The underlying script dumps the full Consul log output to `test.log` in 
   125  the directory of the target package. In the example above it would be 
   126  located at `consul/connect/proxy/test.log`. 
   127  
   128  Historically, the defaults for `FLAKE_CPUS` (30) and `FLAKE_N` (0.15) have been 
   129  sufficient to surface a flaky test. If a test is run in this environment and 
   130  it does not fail after 30 iterations, it should be sufficiently stable.
   131  
   132  ## Vendoring
   133  
   134  Consul currently uses [govendor](https://github.com/kardianos/govendor) for
   135  vendoring and [vendorfmt](https://github.com/magiconair/vendorfmt) for formatting
   136  `vendor.json` to a more merge-friendly "one line per package" format.
   137  
   138  If you are submitting a change that requires new or updated dependencies, 
   139  please include them in `vendor/vendor.json` and in the `vendor/` folder. 
   140  This helps everything get tested properly in CI.
   141  
   142  Use `govendor fetch <project>` to add a project as a dependency. See govendor's [Quick Start](https://github.com/kardianos/govendor#quick-start-also-see-the-faq) for examples.
   143  
   144  Please only apply the minimal vendor changes to get your PR to work. 
   145  Consul does not attempt to track the latest version for each dependency.
   146