mirror of https://github.com/hashicorp/consul
Jack Pearkes
7 years ago
committed by
GitHub
1 changed files with 54 additions and 45 deletions
@ -1,66 +1,75 @@ |
|||||||
**This is a temporary README. We'll restore the old README prior to PR upstream.** |
# Consul [](https://travis-ci.org/hashicorp/consul) [](https://gitter.im/hashicorp-consul/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
||||||
|
|
||||||
# Consul Connect |
* Website: https://www.consul.io |
||||||
|
* Chat: [Gitter](https://gitter.im/hashicorp-consul/Lobby) |
||||||
|
* Mailing list: [Google Groups](https://groups.google.com/group/consul-tool/) |
||||||
|
|
||||||
This repository is the forked repository for Consul Connect work to happen |
Consul is a tool for service discovery and configuration. Consul is |
||||||
in private prior to public release. This README will explain how to safely |
distributed, highly available, and extremely scalable. |
||||||
use this fork, how to bring in upstream changes, etc. |
|
||||||
|
|
||||||
## Cloning |
Consul provides several key features: |
||||||
|
|
||||||
To use this repository, clone it into your GOPATH as usual but you must |
* **Service Discovery** - Consul makes it simple for services to register |
||||||
**rename `consul-connect` to `consul`** so that Go imports continue working |
themselves and to discover other services via a DNS or HTTP interface. |
||||||
as usual. |
External services such as SaaS providers can be registered as well. |
||||||
|
|
||||||
## Important: Never Modify Master |
* **Health Checking** - Health Checking enables Consul to quickly alert |
||||||
|
operators about any issues in a cluster. The integration with service |
||||||
|
discovery prevents routing traffic to unhealthy hosts and enables service |
||||||
|
level circuit breakers. |
||||||
|
|
||||||
**NEVER MODIFY MASTER! NEVER MODIFY MASTER!** |
* **Key/Value Storage** - A flexible key/value store enables storing |
||||||
|
dynamic configuration, feature flagging, coordination, leader election and |
||||||
|
more. The simple HTTP API makes it easy to use anywhere. |
||||||
|
|
||||||
We want to keep the "master" branch equivalent to OSS master. This will make |
* **Multi-Datacenter** - Consul is built to be datacenter aware, and can |
||||||
rebasing easy for master. Instead, we'll use the branch `f-connect`. All |
support any number of regions without complex configuration. |
||||||
feature branches should branch from `f-connect` and make PRs against |
|
||||||
`f-connect`. |
|
||||||
|
|
||||||
When we're ready to merge back to upstream, we can make a single mega PR |
Consul runs on Linux, Mac OS X, FreeBSD, Solaris, and Windows. A commercial |
||||||
merging `f-connect` into OSS master. This way we don't have a sudden mega |
version called [Consul Enterprise](https://www.hashicorp.com/products/consul) |
||||||
push to master on OSS. |
is also available. |
||||||
|
|
||||||
## Creating a Feature Branch |
## Quick Start |
||||||
|
|
||||||
To create a feature branch, branch from `f-connect`: |
An extensive quick start is viewable on the Consul website: |
||||||
|
|
||||||
```sh |
https://www.consul.io/intro/getting-started/install.html |
||||||
git checkout f-connect |
|
||||||
git checkout -b my-new-branch |
|
||||||
``` |
|
||||||
|
|
||||||
All merged Connect features will be in `f-connect`, so you want to work |
## Documentation |
||||||
from that branch. When making a PR for your feature branch, target the |
|
||||||
`f-connect` branch as the merge target. You can do this by using the dropdowns |
|
||||||
in the GitHub UI when creating a PR. |
|
||||||
|
|
||||||
## Syncing Upstream |
Full, comprehensive documentation is viewable on the Consul website: |
||||||
|
|
||||||
First update our local master: |
https://www.consul.io/docs |
||||||
|
|
||||||
```sh |
## Developing Consul |
||||||
# This has to happen on forked master |
|
||||||
git checkout master |
|
||||||
|
|
||||||
# Add upstream to OSS Consul |
If you wish to work on Consul itself, you'll first need [Go](https://golang.org) |
||||||
git remote add upstream https://github.com/hashicorp/consul.git |
installed (version 1.9+ is _required_). Make sure you have Go properly installed, |
||||||
|
including setting up your [GOPATH](https://golang.org/doc/code.html#GOPATH). |
||||||
|
|
||||||
# Fetch it |
Next, clone this repository into `$GOPATH/src/github.com/hashicorp/consul` and |
||||||
git fetch upstream |
then just type `make`. In a few moments, you'll have a working `consul` executable: |
||||||
|
|
||||||
# Rebase forked master onto upstream. This should have no changes since |
``` |
||||||
# we're never modifying master. |
$ make |
||||||
git rebase upstream master |
... |
||||||
|
$ bin/consul |
||||||
|
... |
||||||
``` |
``` |
||||||
|
|
||||||
Next, update the `f-connect` branch: |
*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`.* |
||||||
|
|
||||||
```sh |
*Note: `make` will also place a copy of the binary in the first part of your `$GOPATH`.* |
||||||
git checkout f-connect |
|
||||||
git rebase origin master |
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. |
||||||
|
|||||||
Loading…
Reference in new issue