From 44f76ead6ad2b7ab8d6c476f149c70a468bbcbd7 Mon Sep 17 00:00:00 2001 From: Jack Pearkes Date: Tue, 26 Jun 2018 00:34:18 -0700 Subject: [PATCH] correct README --- README.md | 99 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 54 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 1d7c55f37b..1e29e765f8 100644 --- a/README.md +++ b/README.md @@ -1,66 +1,75 @@ -**This is a temporary README. We'll restore the old README prior to PR upstream.** +# Consul [![Build Status](https://travis-ci.org/hashicorp/consul.svg?branch=master)](https://travis-ci.org/hashicorp/consul) [![Join the chat at https://gitter.im/hashicorp-consul/Lobby](https://badges.gitter.im/hashicorp-consul/Lobby.svg)](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 -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. +## Documentation -## Syncing Upstream +Full, comprehensive documentation is viewable on the Consul website: -First update our local master: +https://www.consul.io/docs -```sh -# This has to happen on forked master -git checkout master +## Developing Consul -# Add upstream to OSS Consul -git remote add upstream https://github.com/hashicorp/consul.git +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). -# Fetch it -git fetch upstream +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: -# Rebase forked master onto upstream. This should have no changes since -# we're never modifying master. -git rebase upstream master +``` +$ make +... +$ 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 -git checkout f-connect -git rebase origin master -``` +*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.