Documentation: Fix heading hierarchy.

Correct the hierarchy of Markdown symbols in document headings.

Documentation/04_to_2_snapshot_migration.md

@@ -1,4 +1,4 @@
-## Snapshot Migration
+# Snapshot Migration
 
 You can migrate a snapshot of your data from a v0.4.9+ cluster into a new etcd 2.2 cluster using a snapshot migration. After snapshot migration, the etcd indexes of your data will change. Many etcd applications rely on these indexes to behave correctly. This operation should only be done while all etcd applications are stopped.
 

Documentation/admin_guide.md

@@ -1,8 +1,8 @@
-## Administration
+# Administration
 
-### Data Directory
+## Data Directory
 
-#### Lifecycle
+### Lifecycle
 
 When first started, etcd stores its configuration into a data directory specified by the data-dir configuration parameter.
 Configuration is stored in the write ahead log and includes: the local member ID, cluster ID, and initial cluster configuration.
@@ -20,7 +20,7 @@ Once removed the member can be re-added with an empty data directory.
 
 [remove-a-member]: runtime-configuration.md#remove-a-member
 
-#### Contents
+### Contents
 
 The data directory has two sub-directories in it:
 
@@ -32,18 +32,18 @@ If `--wal-dir` flag is set, etcd will write the write ahead log files to the spe
 [wal-pkg]: http://godoc.org/github.com/coreos/etcd/wal
 [snap-pkg]: http://godoc.org/github.com/coreos/etcd/snap
 
-### Cluster Management
+## Cluster Management
 
-#### Lifecycle
+### Lifecycle
 
 If you are spinning up multiple clusters for testing it is recommended that you specify a unique initial-cluster-token for the different clusters.
 This can protect you from cluster corruption in case of mis-configuration because two members started with different cluster tokens will refuse members from each other.
 
-#### Monitoring
+### Monitoring
 
 It is important to monitor your production etcd cluster for healthy information and runtime metrics.
 
-##### Health Monitoring
+#### Health Monitoring
 
 At lowest level, etcd exposes health information via HTTP at `/health` in JSON format. If it returns `{"health": "true"}`, then the cluster is healthy. Please note the `/health` endpoint is still an experimental one as in etcd 2.2.
 
@@ -63,16 +63,16 @@ member fd422379fda50e48 is healthy: got healthy result from http://127.0.0.1:323
 cluster is healthy
 ```
 
-##### Runtime Metrics
+#### Runtime Metrics
 
 etcd uses [Prometheus](http://prometheus.io/) for metrics reporting in the server. You can read more through the runtime metrics [doc](metrics.md).
 
-#### Debugging
+### Debugging
 
 Debugging a distributed system can be difficult. etcd provides several ways to make debug
 easier.
 
-##### Enabling Debug Logging
+#### Enabling Debug Logging
 
 When you want to debug etcd without stopping it, you can enable debug logging at runtime.
 etcd exposes logging configuration at `/config/local/log`.
@@ -85,7 +85,7 @@ $ curl http://127.0.0.1:2379/config/local/log -XPUT -d '{"Level":"INFO"}'
 $ # debug logging disabled
 ```
 
-##### Debugging Variables
+#### Debugging Variables
 
 Debug variables are exposed for real-time debugging purposes. Developers who are familiar with etcd can utilize these variables to debug unexpected behavior. etcd exposes debug variables via HTTP at `/debug/vars` in JSON format. The debug variables contains
 `cmdline`, `file_descriptor_limit`, `memstats` and `raft.status`.
@@ -107,7 +107,7 @@ Debug variables are exposed for real-time debugging purposes. Developers who are
 }
 ```
 
-#### Optimal Cluster Size
+### Optimal Cluster Size
 
 The recommended etcd cluster size is 3, 5 or 7, which is decided by the fault tolerance requirement. A 7-member cluster can provide enough fault tolerance in most cases. While larger cluster provides better fault tolerance the write performance reduces since data needs to be replicated to more machines.
 

Documentation/branch_management.md

@@ -1,6 +1,6 @@
-## Branch Management
+# Branch Management
 
-### Guide
+## Guide
 
 - New development occurs on the [master branch](https://github.com/coreos/etcd/tree/master)
 - Master branch should always have a green build!

Documentation/errorcode.md

@@ -1,4 +1,4 @@
-Error Code
+# Error Code
 ======
 
 This document describes the error code used in key space '/v2/keys'. Feel free to import 'github.com/coreos/etcd/error' to use.

Documentation/glossary.md

@@ -1,35 +1,35 @@
-## Glossary
+# Glossary
 
 This document defines the various terms used in etcd documentation, command line and source code.
 
-### Node
+## Node
 
 Node is an instance of raft state machine.
 
 It has a unique identification, and records other nodes' progress internally when it is the leader.
 
-### Member
+## Member
 
 Member is an instance of etcd. It hosts a node, and provides service to clients.
 
-### Cluster
+## Cluster
 
 Cluster consists of several members.
 
 The node in each member follows raft consensus protocol to replicate logs. Cluster receives proposals from members, commits them and apply to local store.
 
-### Peer
+## Peer
 
 Peer is another member of the same cluster.
 
-### Proposal
+## Proposal
 
 A proposal is a request (for example a write request, a configuration change request) that needs to go through raft protocol.
 
-### Client
+## Client
 
 Client is a caller of the cluster's HTTP API.
 
-### Machine (deprecated)
+## Machine (deprecated)
 
 The alternative of Member in etcd before 2.0

Documentation/libraries-and-tools.md

@@ -1,4 +1,4 @@
-## Libraries and Tools
+# Libraries and Tools
 
 **Tools**
 

Documentation/metrics.md

@@ -1,6 +1,6 @@
-## Metrics
+# Metrics
 
-**NOTE: The metrics feature is considered as an experimental. We might add/change/remove metrics without warning in the future releases.**
+**NOTE: The metrics feature is considered experimental. We may add/change/remove metrics without warning in future releases.**
 
 etcd uses [Prometheus](http://prometheus.io/) for metrics reporting in the server. The metrics can be used for real-time monitoring and debugging.
 
@@ -13,7 +13,7 @@ The naming of metrics follows the suggested [best practice of Prometheus](http:/
 
 etcd now exposes the following metrics:
 
-### etcdserver
+## etcdserver
 
 | Name                                    | Description                                      | Type    |
 |-----------------------------------------|--------------------------------------------------|---------|
@@ -30,7 +30,7 @@ Pending proposal (`pending_proposal_total`) gives you an idea about how many pro
 
 Failed proposals (`proposal_failed_total`) are normally related to two issues: temporary failures related to a leader election or longer duration downtime caused by a loss of quorum in the cluster.
 
-### wal
+## wal
 
 | Name                               | Description                                      | Type    |
 |------------------------------------|--------------------------------------------------|---------|
@@ -40,7 +40,7 @@ Failed proposals (`proposal_failed_total`) are normally related to two issues: t
 Abnormally high fsync duration (`fsync_durations_microseconds`) indicates disk issues and might cause the cluster to be unstable.
 
 
-### http requests
+## http requests
 
 These metrics describe the serving of requests (non-watch events) served by etcd members in non-proxy mode: total 
 incoming requests, request failures and processing latency (inc. raft rounds for storage). They are useful for tracking
@@ -71,7 +71,7 @@ Example Prometheus queries that may be useful from these metrics (across all etc
     
     Show the 0.90-tile latency (in seconds) of read/write (respectively) event handling across all members, with a window of `5m`.      
 
-### snapshot
+## snapshot
 
 | Name                                       | Description                                                | Type    |
 |--------------------------------------------|------------------------------------------------------------|---------|
@@ -80,7 +80,7 @@ Example Prometheus queries that may be useful from these metrics (across all etc
 Abnormally high snapshot duration (`snapshot_save_total_durations_microseconds`) indicates disk issues and might cause the cluster to be unstable.
 
 
-### rafthttp
+## rafthttp
 
 | Name                              | Description                                | Type    | Labels                         |
 |-----------------------------------|--------------------------------------------|---------|--------------------------------|
@@ -99,7 +99,7 @@ Label `msgType` is the type of raft message. `MsgApp` is log replication message
 Label `remoteID` is the member ID of the message destination.
 
 
-### proxy
+## proxy
 
 etcd members operating in proxy mode do not do store operations. They forward all requests
  to cluster instances.

Documentation/other_apis.md

@@ -1,4 +1,4 @@
-## Members API
+# Members API
 
 * [List members](#list-members)
 * [Add a member](#add-a-member)
@@ -103,7 +103,7 @@ Change the peer urls of a given member. The member ID must be a hex-encoded uint
 
 If the POST body is malformed an HTTP 400 will be returned. If the member does not exist in the cluster an HTTP 404 will be returned. If any of the given peerURLs exists in the cluster an HTTP 409 will be returned. If the cluster fails to process the request within timeout an HTTP 500 will be returned, though the request may be processed later.
 
-#### Request
+### Request
 
 ```
 PUT /v2/members/<id> HTTP/1.1
@@ -111,7 +111,7 @@ PUT /v2/members/<id> HTTP/1.1
 {"peerURLs": ["http://10.0.0.10:2380"]}
 ```
 
-#### Example
+### Example
 
 ```sh
 curl http://10.0.0.10:2379/v2/members/272e204152 -XPUT \

Documentation/production-ready.md

@@ -1,4 +1,6 @@
+# etcd in Production
+
 etcd is being used successfully by many companies in production. It is,
-however, under active development and systems like etcd are difficult to get
-correct. If you are comfortable with bleeding-edge software please use etcd and
+however, under active development, and systems like etcd are difficult to get
+correct. If you are comfortable with bleeding-edge software, please use etcd and
 provide us with the feedback and testing young software needs.

Documentation/proxy.md

@@ -1,4 +1,4 @@
-## Proxy
+# Proxy
 
 etcd can now run as a transparent proxy. Running etcd as a proxy allows for easy discovery of etcd within your infrastructure, since it can run on each machine as a local service. In this mode, etcd acts as a reverse proxy and forwards client requests to an active etcd cluster. The etcd proxy does not participate in the consensus replication of the etcd cluster, thus it neither increases the resilience nor decreases the write performance of the etcd cluster.
 
@@ -8,14 +8,14 @@ The proxy will shuffle the list of cluster members periodically to avoid sending
 
 The member list used by proxy consists of all client URLs advertised within the cluster, as specified in each members' `-advertise-client-urls` flag. If this flag is set incorrectly, requests sent to the proxy are forwarded to wrong addresses and then fail. Including URLs in the `-advertise-client-urls` flag that point to the proxy itself, e.g. http://localhost:2379, is even more problematic as it will cause loops, because the proxy keeps trying to forward requests to itself until its resources (memory, file descriptors) are eventually depleted. The fix for this problem is to restart etcd member with correct `-advertise-client-urls` flag. After client URLs list in proxy is recalculated, which happens every 30 seconds, requests will be forwarded correctly.
 
-### Using an etcd proxy
+## Using an etcd proxy
 To start etcd in proxy mode, you need to provide three flags: `proxy`, `listen-client-urls`, and `initial-cluster` (or `discovery`). 
 
 To start a readwrite proxy, set `-proxy on`; To start a readonly proxy, set `-proxy readonly`.
 
 The proxy will be listening on `listen-client-urls` and forward requests to the etcd cluster discovered from in `initial-cluster` or `discovery` url. 
 
-#### Start an etcd proxy with a static configuration
+### Start an etcd proxy with a static configuration
 To start a proxy that will connect to a statically defined etcd cluster, specify the `initial-cluster` flag:
 
 ```
@@ -24,7 +24,7 @@ etcd -proxy on \
 -initial-cluster infra0=http://10.0.1.10:2380,infra1=http://10.0.1.11:2380,infra2=http://10.0.1.12:2380
 ```
 
-#### Start an etcd proxy with the discovery service
+### Start an etcd proxy with the discovery service
 If you bootstrap an etcd cluster using the [discovery service][discovery-service], you can also start the proxy with the same `discovery`. 
 
 To start a proxy using the discovery service, specify the `discovery` flag. The proxy will wait until the etcd cluster defined at the `discovery` url finishes bootstrapping, and then start to forward the requests. 
@@ -35,10 +35,11 @@ etcd -proxy on \
 -discovery https://discovery.etcd.io/3e86b59982e49066c5d813af1c2e2579cbf573de
 ```
 
-#### Fallback to proxy mode with discovery service
+## Fallback to proxy mode with discovery service
+
 If you bootstrap a etcd cluster using [discovery service][discovery-service] with more than the expected number of etcd members, the extra etcd processes will fall back to being `readwrite` proxies by default. They will forward the requests to the cluster as described above. For example, if you create a discovery url with `size=5`, and start ten etcd processes using that same discovery url, the result will be a cluster with five etcd members and five proxies. Note that this behaviour can be disabled with the `proxy-fallback` flag.
 
-### Promote a proxy to a member of etcd cluster
+## Promote a proxy to a member of etcd cluster
 
 A Proxy is in the part of etcd cluster that does not participant in consensus. A proxy will not promote itself to an etcd member that participants in consensus automtically in any case.
 
@@ -49,7 +50,7 @@ If you want to promote a proxy to an etcd member, there are four steps you need
 - remove the existing proxy data directory
 - restart the etcd process with new member configuration
 
-#### Example
+## Example
 
 We assume you have a one member etcd cluster with one proxy. The cluster information is listed below:
 

Documentation/reporting_bugs.md

@@ -1,4 +1,4 @@
-## Reporting Bugs
+# Reporting Bugs
 
 If you find bugs or documentation mistakes in etcd project, please let us know by [opening an issue](https://github.com/coreos/etcd/issues/new). We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check there that one does not already exist.
 
@@ -20,7 +20,7 @@ We might ask you for further information to locate a bug. A duplicated bug repor
 
 ## Frequently Asked Questions
 
-### How to get stack trace
+### How to get a stack trace
 
 ``` bash
 $ kill -QUIT $PID

Documentation/rfc/v3api.md

@@ -1,4 +1,4 @@
-## Design
+# Design
 
 1. Flatten binary key-value space
     
@@ -32,9 +32,9 @@
 
 [protobuf](./v3api.proto)
 
-### Examples
+## Examples
 
-#### Put a key (foo=bar)
+### Put a key (foo=bar)
 ```
 // A put is always successful
 Put( PutRequest { key = foo, value = bar } )
@@ -47,7 +47,7 @@ PutResponse {
 }
 ```
 
-#### Get a key (assume we have foo=bar)
+### Get a key (assume we have foo=bar)
 ```
 Get ( RangeRequest { key = foo } )
 
@@ -68,7 +68,7 @@ RangeResponse {
 }
 ```
 
-#### Range over a key space (assume we have foo0=bar0… foo100=bar100)
+### Range over a key space (assume we have foo0=bar0… foo100=bar100)
 ```
 Range ( RangeRequest { key = foo, end_key = foo80, limit = 30  } )
 
@@ -97,7 +97,7 @@ RangeResponse {
 }
 ```
 
-#### Finish a txn (assume we have foo0=bar0, foo1=bar1)
+### Finish a txn (assume we have foo0=bar0, foo1=bar1)
 ```
 Txn(TxnRequest {
     // mod_revision of foo0 is equal to 1, mod_revision of foo1 is greater than 1
@@ -129,7 +129,7 @@ TxnResponse {
 }
 ```
 
-#### Watch on a key/range
+### Watch on a key/range
 
 ```
 Watch( WatchRequest{

Documentation/runtime-configuration.md

@@ -1,4 +1,4 @@
-## Runtime Reconfiguration
+# Runtime Reconfiguration
 
 etcd comes with support for incremental runtime reconfiguration, which allows users to update the membership of the cluster at run time.
 
@@ -131,7 +131,7 @@ The new member will run as a part of the cluster and immediately begin catching
 If you are adding multiple members the best practice is to configure a single member at a time and verify it starts correctly before adding more new members.
 If you add a new member to a 1-node cluster, the cluster cannot make progress before the new member starts because it needs two members as majority to agree on the consensus. You will only see this behavior between the time `etcdctl member add` informs the cluster about the new member and the new member successfully establishing a connection to the existing one.
 
-#### Error Cases
+#### Error Cases When Adding Members
 
 In the following case we have not included our new host in the list of enumerated nodes.
 If this is a new cluster, the node must be added to the list of initial cluster members.
@@ -162,7 +162,7 @@ etcd: this member has been permanently removed from the cluster. Exiting.
 exit 1
 ```
 
-#### Strict Reconfiguration Check Mode (`-strict-reconfig-check`)
+### Strict Reconfiguration Check Mode (`-strict-reconfig-check`)
 
 As described in the above, the best practice of adding new members is to configure a single member at a time and verify it starts correctly before adding more new members. This step by step approach is very important because if newly added members is not configured correctly (for example the peer URLs are incorrect), the cluster can lose quorum. The quorum loss happens since the newly added member are counted in the quorum even if that member is not reachable from other existing members. Also quorum loss might happen if there is a connectivity issue or there are operational issues.
 

Documentation/runtime-reconf-design.md

@@ -1,10 +1,10 @@
-### Design of Runtime Reconfiguration
+# Design of Runtime Reconfiguration
 
 Runtime reconfiguration is one of the hardest and most error prone features in a distributed system, especially in a consensus based system like etcd.
 
 Read on to learn about the design of etcd's runtime reconfiguration commands and how we tackled these problems.
 
-### Two Phase Config Changes Keep you Safe
+## Two Phase Config Changes Keep you Safe
 
 In etcd, every runtime reconfiguration has to go through [two phases](Documentation/runtime-configuration.md#add-a-new-member) for safety reasons. For example, to add a member you need to first inform cluster of new configuration and then start the new member.
 
@@ -22,7 +22,7 @@ Without the explicit workflow around cluster membership etcd would be vulnerable
 
 We think runtime reconfiguration should be a low frequent operation. We made the decision to keep it explicit and user-driven to ensure configuration safety and keep your cluster always running smoothly under your control.
 
-### Permanent Loss of Quorum Requires New Cluster
+## Permanent Loss of Quorum Requires New Cluster
 
 If a cluster permanently loses a majority of its members, a new cluster will need to be started from an old data directory to recover the previous state.
 
@@ -30,7 +30,7 @@ It is entirely possible to force removing the failed members from the existing c
 
 If you have a correct deployment, the possibility of permanent majority lose is very low. But it is a severe enough problem that worth special care. We strongly suggest you to read the [disaster recovery documentation](admin_guide.md#disaster-recovery) and prepare for permanent majority lose before you put etcd into production.
 
-### Do Not Use Public Discovery Service For Runtime Reconfiguration
+## Do Not Use Public Discovery Service For Runtime Reconfiguration
 
 The public discovery service should only be used for bootstrapping a cluster. To join member into an existing cluster, you should use runtime reconfiguration API. 
 

Documentation/tuning.md

@@ -1,11 +1,11 @@
-## Tuning
+# Tuning
 
 The default settings in etcd should work well for installations on a local network where the average network latency is low.
 However, when using etcd across multiple data centers or over networks with high latency you may need to tweak the heartbeat interval and election timeout settings.
 
 The network isn't the only source of latency. Each request and response may be impacted by slow disks on both the leader and follower. Each of these timeouts represents the total time from request to successful response from the other machine.
 
-### Time Parameters
+## Time Parameters
 
 The underlying distributed consensus protocol relies on two separate time parameters to ensure that nodes can handoff leadership if one stalls or goes offline.
 The first parameter is called the *Heartbeat Interval*.
@@ -49,7 +49,7 @@ $ ETCD_HEARTBEAT_INTERVAL=100 ETCD_ELECTION_TIMEOUT=500 etcd
 
 The values are specified in milliseconds.
 
-### Snapshots
+## Snapshots
 
 etcd appends all key changes to a log file.
 This log grows forever and is a complete linear history of every change made to the keys.

Documentation/upgrade_2_1.md

@@ -1,4 +1,4 @@
-## Upgrade etcd to 2.1
+# Upgrade etcd to 2.1
 
 In the general case, upgrading from etcd 2.0 to 2.1 can be a zero-downtime, rolling upgrade:
  - one by one, stop the etcd v2.0 processes and replace them with etcd v2.1 processes
@@ -6,15 +6,15 @@ In the general case, upgrading from etcd 2.0 to 2.1 can be a zero-downtime, roll
 
 Before [starting an upgrade](#upgrade-procedure), read through the rest of this guide to prepare.
 
-### Upgrade Checklists
+## Upgrade Checklists
 
-#### Upgrade Requirement
+### Upgrade Requirements
 
 To upgrade an existing etcd deployment to 2.1, you must be running 2.0. If you’re running a version of etcd before 2.0, you must upgrade to [2.0](https://github.com/coreos/etcd/releases/tag/v2.0.13) before upgrading to 2.1.
 
 Also, to ensure a smooth rolling upgrade, your running cluster must be healthy. You can check the health of the cluster by using `etcdctl cluster-health` command. 
 
-#### Preparedness 
+### Preparedness 
 
 Before upgrading etcd, always test the services relying on etcd in a staging environment before deploying the upgrade to the production environment. 
 
@@ -22,13 +22,13 @@ You might also want to [backup your data directory](admin_guide.md#backing-up-th
 
 etcd 2.1 introduces a new [authentication](auth_api.md) feature, which is disabled by default. If your deployment depends on these, you may want to test the auth features before enabling them in production.
 
-#### Mixed Versions
+### Mixed Versions
 
 While upgrading, an etcd cluster supports mixed versions of etcd members. The cluster is only considered upgraded once all its members are upgraded to 2.1.
 
 Internally, etcd members negotiate with each other to determine the overall etcd cluster version, which controls the reported cluster version and the supported features. For example, if you are mid-upgrade, any 2.1 features (such as the the authentication feature mentioned above) won’t be available.
 
-#### Limitations
+### Limitations
 
 If you encounter any issues during the upgrade, you can attempt to restart the etcd process in trouble using a newer v2.1 binary to solve the problem. One known issue is that etcd v2.0.0 and v2.0.2 may panic during rolling upgrades due to an existing bug, which has been fixed since etcd v2.0.3.
 
@@ -36,7 +36,7 @@ It might take up to 2 minutes for the newly upgraded member to catch up with the
 
 If you have even more data, this might take more time. If you have a data size larger than 100MB you should contact us before upgrading, so we can make sure the upgrades work smoothly.
 
-#### Downgrade
+### Downgrade
 
 If all members have been upgraded to v2.1, the cluster will be upgraded to v2.1, and downgrade is **not possible**. If any member is still v2.0, the cluster will remain in v2.0, and you can go back to use v2.0 binary. 
 

Documentation/upgrade_2_2.md

@@ -1,4 +1,4 @@
-## Upgrade etcd from 2.1 to 2.2
+# Upgrade etcd from 2.1 to 2.2
 
 In the general case, upgrading from etcd 2.1 to 2.2 can be a zero-downtime, rolling upgrade:
 
@@ -7,33 +7,33 @@ In the general case, upgrading from etcd 2.1 to 2.2 can be a zero-downtime, roll
 
 Before [starting an upgrade](#upgrade-procedure), read through the rest of this guide to prepare.
 
-### Upgrade Checklists
+## Upgrade Checklists
 
-#### Upgrade Requirement
+### Upgrade Requirement
 
 To upgrade an existing etcd deployment to 2.2, you must be running 2.1. If you’re running a version of etcd before 2.1, you must upgrade to [2.1](https://github.com/coreos/etcd/releases/tag/v2.1.2) before upgrading to 2.2.
 
 Also, to ensure a smooth rolling upgrade, your running cluster must be healthy. You can check the health of the cluster by using `etcdctl cluster-health` command. 
 
-#### Preparedness 
+### Preparedness 
 
 Before upgrading etcd, always test the services relying on etcd in a staging environment before deploying the upgrade to the production environment. 
 
 You might also want to [backup your data directory](admin_guide.md#backing-up-the-datastore) for a potential [downgrade](#downgrade).
 
-#### Mixed Versions
+### Mixed Versions
 
 While upgrading, an etcd cluster supports mixed versions of etcd members. The cluster is only considered upgraded once all its members are upgraded to 2.2.
 
 Internally, etcd members negotiate with each other to determine the overall etcd cluster version, which controls the reported cluster version and the supported features.
 
-#### Limitations
+### Limitations
 
 If you have a data size larger than 100MB you should contact us before upgrading, so we can make sure the upgrades work smoothly.
 
 Every etcd 2.2 member will do health checking across the cluster periodically. etcd 2.1 member does not support health checking. During the upgrade, etcd 2.2 member will log warning about the unhealthy state of etcd 2.1 member. You can ignore the warning. 
 
-#### Downgrade
+### Downgrade
 
 If all members have been upgraded to v2.2, the cluster will be upgraded to v2.2, and downgrade is **not possible**. If any member is still v2.1, the cluster will remain in v2.1, and you can go back to use v2.1 binary.