Contribution guide (#4704)
* Add a contribution guide and link to it from readme * Add first pass at testing section for contribution guide * Format as in README.md * Add responding to community questions as way to contribute
This commit is contained in:
Freddy
Jack Pearkes
parent
851bf8c2eb
commit
83541c2f10
|
|
@ -0,0 +1,146 @@
|
|||
# Contributing to Consul
|
||||
>**Note:** We take Consul's security and our users' trust very seriously.
|
||||
>If you believe you have found a security issue in Consul, please responsibly
|
||||
>disclose by contacting us at security@hashicorp.com.
|
||||
|
||||
**First:** if you're unsure or afraid of _anything_, just ask or submit the
|
||||
issue or pull request anyways. You won't be yelled at for giving your best
|
||||
effort. The worst that can happen is that you'll be politely asked to change
|
||||
something. We appreciate any sort of contributions, and don't want a wall of
|
||||
rules to get in the way of that.
|
||||
|
||||
That said, if you want to ensure that a pull request is likely to be merged,
|
||||
talk to us! A great way to do this is in issues themselves. When you want to
|
||||
work on an issue, comment on it first and tell us the approach you want to take.
|
||||
|
||||
## Getting Started
|
||||
### Some Ways to Contribute
|
||||
* Report potential bugs.
|
||||
* Suggest product enhancements.
|
||||
* Increase our test coverage.
|
||||
* Fix a [bug](https://github.com/hashicorp/consul/labels/bug).
|
||||
* Implement a requested [enhancement](https://github.com/hashicorp/consul/labels/enhancement).
|
||||
* 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)
|
||||
are deployed from this repo.
|
||||
* Respond to questions about usage on the issue tracker or mailing list.
|
||||
|
||||
### Reporting an Issue:
|
||||
>Note: Issues on GitHub for Consul are intended to be related to bugs or feature requests.
|
||||
>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).
|
||||
|
||||
* Make sure you test against the latest released version. It is possible we
|
||||
already fixed the bug you're experiencing. However, if you are on an older
|
||||
version of Consul and feel the issue is critical, do let us know.
|
||||
|
||||
* Check existing issues (both open and closed) to make sure it has not been
|
||||
reported previously.
|
||||
|
||||
* Provide a reproducible test case. If a contributor can't reproduce an issue,
|
||||
then it dramatically lowers the chances it'll get fixed.
|
||||
|
||||
* Aim to respond promptly to any questions made by the Consul team on your
|
||||
issue. Stale issues will be closed.
|
||||
|
||||
### Issue Lifecycle
|
||||
|
||||
1. The issue is reported.
|
||||
|
||||
2. The issue is verified and categorized by a Consul maintainer.
|
||||
Categorization is done via tags. For example, bugs are tagged as "bug".
|
||||
|
||||
3. Unless it is critical, the issue is left for a period of time (sometimes many
|
||||
weeks), giving outside contributors a chance to address the issue.
|
||||
|
||||
4. The issue is addressed in a pull request or commit. The issue will be
|
||||
referenced in the commit message so that the code that fixes it is clearly
|
||||
linked.
|
||||
|
||||
5. The issue is closed.
|
||||
|
||||
## Building Consul
|
||||
|
||||
If you wish to work on Consul itself, you'll first need [Go](https://golang.org)
|
||||
installed (version 1.10+ is _required_). Make sure you have Go properly installed,
|
||||
including setting up your [GOPATH](https://golang.org/doc/code.html#GOPATH).
|
||||
|
||||
Next, clone this repository into `$GOPATH/src/github.com/hashicorp/consul` and
|
||||
then run `make dev`. In a few moments, you'll have a working `consul` executable
|
||||
in `consul/bin` and `$GOPATH/bin`:
|
||||
|
||||
>Note: `make dev` will build for your local machine's os/architecture. If you wish to build for all os/architecture combinations use `make`.
|
||||
|
||||
## Making Changes to Consul
|
||||
|
||||
The first step to making changes is to fork Consul. Afterwards, the easiest way
|
||||
to work on the fork is to set it as a remote of the Consul project:
|
||||
|
||||
1. Navigate to `$GOPATH/src/github.com/hashicorp/consul`
|
||||
2. Rename the existing remote's name: `git remote rename origin upstream`.
|
||||
3. Add your fork as a remote by running
|
||||
`git remote add origin <github url of fork>`. For example:
|
||||
`git remote add origin https://github.com/myusername/consul`.
|
||||
4. Checkout a feature branch: `git checkout -t -b new-feature`
|
||||
5. Make changes
|
||||
6. Push changes to the fork when ready to submit PR:
|
||||
`git push -u origin new-feature`
|
||||
|
||||
By following these steps you can push to your fork to create a PR, but the code on disk still
|
||||
lives in the spot where the go cli tools are expecting to find it.
|
||||
|
||||
>Note: If you make any changes to the code, run `make format` to automatically format the code according to Go standards.
|
||||
|
||||
## Testing
|
||||
|
||||
Before submitting changes, run **all** tests locally by typing `make test`.
|
||||
The test suite may fail if over-parallelized, so if you are seeing stochastic
|
||||
failures try `GOTEST_FLAGS="-p 2 -parallel 2" make test`.
|
||||
|
||||
Certain testing patterns such as creating a test `Client` in the `api` pkg
|
||||
or a `TestAgent` followed by a session can lead to flaky tests. More generally,
|
||||
any tests with components that rely on readiness of other components are often
|
||||
flaky.
|
||||
|
||||
Our makefile has some tooling built in to help validate the stability of single
|
||||
or package-wide tests. By running the `test-flake` goal we spin up a local docker
|
||||
container that mirrors a CPU constrained version of our CI environment. Here we can
|
||||
surface uncommon failures that are typically hard to reproduce by re-running
|
||||
tests multiple times.
|
||||
|
||||
The makefile goal accepts the following variables as arguments:
|
||||
|
||||
* **FLAKE_PKG** Target package (required)
|
||||
|
||||
* **FLAKE_TEST** Target test
|
||||
|
||||
* **FLAKE_CPUS** Amount of CPU resources for container
|
||||
|
||||
* **FLAKE_N** Number of times to run tests
|
||||
|
||||
Examples:
|
||||
`make test-flake FLAKE_PKG=connect/proxy`
|
||||
`make test-flake FLAKE_PKG=connect/proxy FLAKE_TEST=TestUpstreamListener`
|
||||
`make test-flake FLAKE_PKG=connect/proxy FLAKE_TEST=TestUpstreamListener FLAKE_CPUS=0.15 FLAKE_N=30`
|
||||
|
||||
The underlying script dumps the full Consul log output to `test.log` in
|
||||
the directory of the target package. In the example above it would be
|
||||
located at `consul/connect/proxy/test.log`.
|
||||
|
||||
Historically, the defaults for `FLAKE_CPUS` (30) and `FLAKE_N` (0.15) have been
|
||||
sufficient to surface a flaky test. If a test is run in this environment and
|
||||
it does not fail after 30 iterations, it should be sufficiently stable.
|
||||
|
||||
## Vendoring
|
||||
|
||||
Consul currently uses [govendor](https://github.com/kardianos/govendor) for
|
||||
vendoring and [vendorfmt](https://github.com/magiconair/vendorfmt) for formatting
|
||||
`vendor.json` to a more merge-friendly "one line per package" format.
|
||||
|
||||
If you are submitting a change that requires new or updated dependencies,
|
||||
please include them in `vendor/vendor.json` and in the `vendor/` folder.
|
||||
This helps everything get tested properly in CI.
|
||||
|
||||
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.
|
||||
|
||||
Please only apply the minimal vendor changes to get your PR to work.
|
||||
Consul does not attempt to track the latest version for each dependency.
|
||||
|
||||
33
README.md
33
README.md
|
|
@ -48,35 +48,6 @@ Full, comprehensive documentation is viewable on the Consul website:
|
|||
|
||||
https://www.consul.io/docs
|
||||
|
||||
## Developing Consul
|
||||
## Contributing
|
||||
|
||||
If you wish to work on Consul itself, you'll first need [Go](https://golang.org)
|
||||
installed (version 1.10+ is _required_). Make sure you have Go properly installed,
|
||||
including setting up your [GOPATH](https://golang.org/doc/code.html#GOPATH).
|
||||
|
||||
Next, clone this repository into `$GOPATH/src/github.com/hashicorp/consul` and
|
||||
then just type `make`. In a few moments, you'll have a working `consul` executable:
|
||||
|
||||
```
|
||||
$ make
|
||||
...
|
||||
$ bin/consul
|
||||
...
|
||||
```
|
||||
|
||||
*Note: `make` will build all os/architecture combinations. Set the environment variable `CONSUL_DEV=1` to build it just for your local machine's os/architecture, or use `make dev`.*
|
||||
|
||||
*Note: `make` will also place a copy of the binary in the first part of your `$GOPATH`.*
|
||||
|
||||
You can run tests by typing `make test`. The test suite may fail if
|
||||
over-parallelized, so if you are seeing stochastic failures try
|
||||
`GOTEST_FLAGS="-p 2 -parallel 2" make test`.
|
||||
|
||||
If you make any changes to the code, run `make format` in order to automatically
|
||||
format the code according to Go standards.
|
||||
|
||||
## Vendoring
|
||||
|
||||
Consul currently uses [govendor](https://github.com/kardianos/govendor) for
|
||||
vendoring and [vendorfmt](https://github.com/magiconair/vendorfmt) for formatting
|
||||
`vendor.json` to a more merge-friendly "one line per package" format.
|
||||
Thank you for your interest in contributing! Please refer to [CONTRIBUTING.md](https://github.com/hashicorp/consul/blob/master/.github/CONTRIBUTING.md) for guidance.
|
||||
Loading…
Reference in New Issue