mirror of https://github.com/hashicorp/consul
correct README
Jack Pearkes
GitHub
parent
b5abf61963
commit
44f76ead6a
105
README.md
105
README.md
|
|
@ -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
|
||||
in private prior to public release. This README will explain how to safely
|
||||
use this fork, how to bring in upstream changes, etc.
|
||||
Consul is a tool for service discovery and configuration. Consul is
|
||||
distributed, highly available, and extremely scalable.
|
||||
|
||||
## Cloning
|
||||
Consul provides several key features:
|
||||
|
||||
To use this repository, clone it into your GOPATH as usual but you must
|
||||
**rename `consul-connect` to `consul`** so that Go imports continue working
|
||||
as usual.
|
||||
* **Service Discovery** - Consul makes it simple for services to register
|
||||
themselves and to discover other services via a DNS or HTTP interface.
|
||||
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
|
||||
rebasing easy for master. Instead, we'll use the branch `f-connect`. All
|
||||
feature branches should branch from `f-connect` and make PRs against
|
||||
`f-connect`.
|
||||
* **Multi-Datacenter** - Consul is built to be datacenter aware, and can
|
||||
support any number of regions without complex configuration.
|
||||
|
||||
When we're ready to merge back to upstream, we can make a single mega PR
|
||||
merging `f-connect` into OSS master. This way we don't have a sudden mega
|
||||
push to master on OSS.
|
||||
Consul runs on Linux, Mac OS X, FreeBSD, Solaris, and Windows. A commercial
|
||||
version called [Consul Enterprise](https://www.hashicorp.com/products/consul)
|
||||
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
|
||||
git checkout f-connect
|
||||
git checkout -b my-new-branch
|
||||
https://www.consul.io/intro/getting-started/install.html
|
||||
|
||||
## Documentation
|
||||
|
||||
Full, comprehensive documentation is viewable on the Consul website:
|
||||
|
||||
https://www.consul.io/docs
|
||||
|
||||
## Developing Consul
|
||||
|
||||
If you wish to work on Consul itself, you'll first need [Go](https://golang.org)
|
||||
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).
|
||||
|
||||
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
|
||||
...
|
||||
```
|
||||
|
||||
All merged Connect features will be in `f-connect`, so you want to work
|
||||
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.
|
||||
*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`.*
|
||||
|
||||
## Syncing Upstream
|
||||
*Note: `make` will also place a copy of the binary in the first part of your `$GOPATH`.*
|
||||
|
||||
First update our local 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`.
|
||||
|
||||
```sh
|
||||
# This has to happen on forked master
|
||||
git checkout master
|
||||
If you make any changes to the code, run `make format` in order to automatically
|
||||
format the code according to Go standards.
|
||||
|
||||
# Add upstream to OSS Consul
|
||||
git remote add upstream https://github.com/hashicorp/consul.git
|
||||
## Vendoring
|
||||
|
||||
# Fetch it
|
||||
git fetch upstream
|
||||
|
||||
# Rebase forked master onto upstream. This should have no changes since
|
||||
# we're never modifying master.
|
||||
git rebase upstream master
|
||||
```
|
||||
|
||||
Next, update the `f-connect` branch:
|
||||
|
||||
```sh
|
||||
git checkout f-connect
|
||||
git rebase origin master
|
||||
```
|
||||
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