Merge pull request #5782 from heyitsanthony/doc-lint

Documentation: conform to header style

CONTRIBUTING.md

@@ -12,7 +12,7 @@ etcd is Apache 2.0 licensed and accepts contributions via GitHub pull requests.
 - Fork the repository on GitHub
 - Read the README.md for build instructions
 
-## Reporting Bugs and Creating Issues
+## Reporting bugs and creating issues
 
 Reporting bugs is one of the best ways to contribute. However, a good bug report
 has some very specific qualities, so please read over our short document on
@@ -39,7 +39,7 @@ The coding style suggested by the Golang community is used in etcd. See the [sty
 
 Please follow this style to make etcd easy to review, maintain and develop.
 
-### Format of the Commit Message
+### Format of the commit message
 
 We follow a rough convention for commit messages that is designed to answer two
 questions: what changed and why. The subject line should feature the what and

Documentation/branch_management.md

@@ -1,4 +1,4 @@
-# Branch Management
+# Branch management
 
 ## Guide
 

Documentation/dev-guide/local_cluster.md

@@ -1,8 +1,8 @@
-# Setup a Local Cluster
+# Setup a local cluster
 
 For testing and development deployments, the quickest and easiest way is to set up a local cluster. For a production deployment, refer to the [clustering][clustering] section.
 
-## Local Standalone Cluster
+## Local standalone cluster
 
 Deploying an etcd cluster as a standalone cluster is straightforward. Start it with just one command:
 
@@ -26,7 +26,7 @@ $ ./etcdctl get foo
 bar
 ```
 
-## Local Multi-member Cluster
+## Local multi-member cluster
 
 A Procfile is provided to easily set up a local multi-member cluster. Start a multi-member cluster with a few commands:
 

Documentation/dev-internal/discovery_protocol.md

@@ -1,4 +1,4 @@
-# Discovery Service Protocol
+# Discovery service protocol
 
 Discovery service protocol helps new etcd member to discover all other members in cluster bootstrap phase using a shared discovery URL.
 
@@ -8,7 +8,7 @@ The protocol uses a new discovery token to bootstrap one _unique_ etcd cluster.
 
 The rest of this article will walk through the discovery process with examples that correspond to a self-hosted discovery cluster. The public discovery service, discovery.etcd.io, functions the same way, but with a layer of polish to abstract away ugly URLs, generate UUIDs automatically, and provide some protections against excessive requests. At its core, the public discovery service still uses an etcd cluster as the data store as described in this document.
 
-## The Protocol Workflow
+## Protocol workflow
 
 The idea of discovery protocol is to use an internal etcd cluster to coordinate bootstrap of a new cluster. First, all new members interact with discovery service and help to generate the expected member list. Then each new member bootstraps its server using this list, which performs the same functionality as -initial-cluster flag.
 
@@ -16,7 +16,7 @@ In the following example workflow, we will list each step of protocol in curl fo
 
 By convention the etcd discovery protocol uses the key prefix `_etcd/registry`. If `http://example.com` hosts an etcd cluster for discovery service, a full URL to discovery keyspace will be `http://example.com/v2/keys/_etcd/registry`. We will use this as the URL prefix in the example.
 
-### Creating a New Discovery Token
+### Creating a new discovery token
 
 Generate a unique token that will identify the new cluster. This will be used as a unique prefix in discovery keyspace in the following steps. An easy way to do this is to use `uuidgen`:
 
@@ -24,7 +24,7 @@ Generate a unique token that will identify the new cluster. This will be used as
 UUID=$(uuidgen)
 ```
 
-### Specifying the Expected Cluster Size
+### Specifying the expected cluster size
 
 The discovery token expects a cluster size that must be specified. The size is used by the discovery service to know when it has found all members that will initially form the cluster.
 
@@ -34,7 +34,7 @@ curl -X PUT http://example.com/v2/keys/_etcd/registry/${UUID}/_config/size -d va
 
 Usually the cluster size is 3, 5 or 7. Check [optimal cluster size][cluster-size] for more details.
 
-### Bringing up etcd Processes
+### Bringing up etcd processes
 
 Given the discovery URL, use it as `-discovery` flag and bring up etcd processes. Every etcd process will follow this next few steps internally if given a `-discovery` flag.
 
@@ -46,7 +46,7 @@ The first thing for etcd process is to register itself into the discovery URL as
 curl -X PUT http://example.com/v2/keys/_etcd/registry/${UUID}/${member_id}?prevExist=false -d value="${member_name}=${member_peer_url_1}&${member_name}=${member_peer_url_2}"
 ```
 
-### Checking the Status
+### Checking the status
 
 It checks the expected cluster size and registration status in discovery URL, and decides what the next action is.
 
@@ -61,8 +61,7 @@ If the number of registered members is bigger than the expected size N, it treat
 
 In etcd implementation, the member may check the cluster status even before registering itself. So it could fail quickly if the cluster has been full.
 
-### Waiting for All Members
-
+### Waiting for all members
 
 The wait process is described in detail in the [etcd API documentation][api].
 
@@ -72,11 +71,11 @@ curl -X GET http://example.com/v2/keys/_etcd/registry/${UUID}?wait=true&waitInde
 
 It keeps waiting until finding all members.
 
-## Public Discovery Service
+## Public discovery service
 
 CoreOS Inc. hosts a public discovery service at https://discovery.etcd.io/ , which provides some nice features for ease of use.
 
-### Mask Key Prefix
+### Mask key prefix
 
 Public discovery service will redirect `https://discovery.etcd.io/${UUID}` to etcd cluster behind for the key at `/v2/keys/_etcd/registry`. It masks register key prefix for short and readable discovery url.
 
@@ -96,7 +95,7 @@ Possible status codes:
 
 The generation process in the service follows the steps from [Creating a New Discovery Token][new-discovery-token] to [Specifying the Expected Cluster Size][expected-cluster-size].
 
-### Check Discovery Status
+### Check discovery status
 
 ```
 GET /${UUID}

Documentation/dev-internal/logging.md

@@ -1,4 +1,4 @@
-# Logging Conventions
+# Logging conventions
 
 etcd uses the [capnslog][capnslog] library for logging application output categorized into *levels*. A log message's level is determined according to these conventions:
 
@@ -26,4 +26,4 @@ etcd uses the [capnslog][capnslog] library for logging application output catego
     * Send a normal message to a remote peer
     * Write a log entry to disk
 
-[capnslog]: [https://github.com/coreos/pkg/tree/master/capnslog]
+[capnslog]: [https://github.com/coreos/pkg/tree/master/capnslog]

Documentation/dev-internal/release.md

@@ -4,7 +4,7 @@ The guide talks about how to release a new version of etcd.
 
 The procedure includes some manual steps for sanity checking but it can probably be further scripted. Please keep this document up-to-date if making changes to the release process. 
 
-## Prepare Release
+## Prepare release
 
 Set desired version as environment variable for following steps. Here is an example to release 2.3.0:
 
@@ -15,7 +15,7 @@ export PREV_VERSION=v2.2.5
 
 All releases version numbers follow the format of [semantic versioning 2.0.0](http://semver.org/).
 
-### Major, Minor Version Release, or its Pre-release
+### Major, minor version release, or its pre-release
 
 - Ensure the relevant milestone on GitHub is complete. All referenced issues should be closed, or moved elsewhere.
 - Remove this release from [roadmap](https://github.com/coreos/etcd/blob/master/ROADMAP.md), if necessary.
@@ -23,18 +23,18 @@ All releases version numbers follow the format of [semantic versioning 2.0.0](ht
 - Bump [hardcoded MinClusterVerion in the repository](https://github.com/coreos/etcd/blob/master/version/version.go#L29), if necessary.
 - Add feature capability maps for the new version, if necessary.
 
-### Patch Version Release
+### Patch version release
 
 - Discuss about commits that are backported to the patch release. The commits should not include merge commits.
 - Cherry-pick these commits starting from the oldest one into stable branch.
 
-## Write Release Note
+## Write release note
 
 - Write introduction for the new release. For example, what major bug we fix, what new features we introduce or what performance improvement we make.
 - Write changelog for the last release. ChangeLog should be straightforward and easy to understand for the end-user.
 - Put `[GH XXXX]` at the head of change line to reference Pull Request that introduces the change. Moreover, add a link on it to jump to the Pull Request.
 
-## Tag Version
+## Tag version
 
 - Bump [hardcoded Version in the repository](https://github.com/coreos/etcd/blob/master/version/version.go#L30) to the latest version `${VERSION}`.
 - Ensure all tests on CI system are passed.
@@ -45,7 +45,7 @@ All releases version numbers follow the format of [semantic versioning 2.0.0](ht
 - Sanity check tag correctness through `git show tags/$VERSION`.
 - Push the tag to GitHub through `git push origin tags/$VERSION`. This assumes `origin` corresponds to "https://github.com/coreos/etcd".
 
-## Build Release Binaries and Images
+## Build release binaries and images
 
 - Ensure `actool` is available, or installing it through `go get github.com/appc/spec/actool`.
 - Ensure `docker` is available.
@@ -58,7 +58,7 @@ Run release script in root directory:
 
 It generates all release binaries and images under directory ./release.
 
-## Sign Binaries and Images
+## Sign binaries and images
 
 etcd project key must be used to sign the generated binaries and images.`$SUBKEYID` is the key ID of etcd project Yubikey. Connect the key and run `gpg2 --card-status` to get the ID.
 
@@ -73,7 +73,7 @@ for i in etcd-*{.zip,.tar.gz}; do gpg2 --verify ${i}.asc ${i}; done
 The public key for GPG signing can be found at [CoreOS Application Signing Key](https://coreos.com/security/app-signing-key)
 
 
-## Publish Release Page in GitHub
+## Publish release page in GitHub
 
 - Set release title as the version name.
 - Follow the format of previous release pages.
@@ -81,7 +81,7 @@ The public key for GPG signing can be found at [CoreOS Application Signing Key](
 - Select whether it is a pre-release.
 - Publish the release!
 
-## Publish Docker Image in Quay.io
+## Publish docker image in Quay.io
 
 - Push docker image:
 
@@ -92,7 +92,7 @@ docker push quay.io/coreos/etcd:${VERSION}
 
 - Add `latest` tag to the new image on [quay.io](https://quay.io/repository/coreos/etcd?tag=latest&tab=tags) if this is a stable release.
 
-## Announce to etcd-dev Googlegroup
+## Announce to the etcd-dev Googlegroup
 
 - Follow the format of [previous release emails](https://groups.google.com/forum/#!forum/etcd-dev).
 - Make sure to include a list of authors that contributed since the previous release - something like the following might be handy:
@@ -103,7 +103,7 @@ git log ...${PREV_VERSION} --pretty=format:"%an" | sort | uniq | tr '\n' ',' | s
 
 - Send email to etcd-dev@googlegroups.com
 
-## Post Release
+## Post release
 
 - Create new stable branch through `git push origin ${VERSION_MAJOR}.${VERSION_MINOR}` if this is a major stable release. This assumes `origin` corresponds to "https://github.com/coreos/etcd".
 - Bump [hardcoded Version in the repository](https://github.com/coreos/etcd/blob/master/version/version.go#L30) to the version `${VERSION}+git`.

Documentation/dl_build.md

@@ -1,14 +1,14 @@
-# Download and Build
+# Download and build
 
-## System Requirements
+## System requirements
 
 TODO
 
-## Download the Pre-built Binary
+## Download the pre-built binary
 
 The easiest way to get etcd is to use one of the pre-built release binaries which are available for OSX, Linux, Windows, appc, and Docker. Instructions for using these binaries are on the [GitHub releases page][github-release].
 
-## Build the Latest Version
+## Build the latest version
 
 For those wanting to try the very latest version, build etcd from the `master` branch.
 [Go](https://golang.org/) version 1.5+ is required to build the latest version of etcd.

Documentation/learning/api.md

@@ -2,7 +2,7 @@
 
 NOTE: this doc is not finished!
 
-## Response Header
+## Response header
 
 All Responses from etcd API have a [response header][response_header] attached. The response header includes the metadata of the response.
 
@@ -30,7 +30,7 @@ Applications can use `Raft_Term` to detect when the cluster completes a new lead
 
 Key-Value API is used to manipulate key-value pairs stored inside etcd. The key-value API is defined as a [gRPC service][kv-service]. The Key-Value pair is defined as structured data in [protobuf format][kv-proto].
 
-### Key-Value Pair
+### Key-Value pair
 
 A key-value pair is the smallest unit that the key-value API can manipulate. Each key-value pair has a number of fields:
 
@@ -54,4 +54,4 @@ message KeyValue {
 
 [kv-proto]: https://github.com/coreos/etcd/blob/master/mvcc/mvccpb/kv.proto
 [kv-service]: https://github.com/coreos/etcd/blob/master/etcdserver/etcdserverpb/rpc.proto
-[response_header]: https://github.com/coreos/etcd/blob/master/etcdserver/etcdserverpb/rpc.proto
+[response_header]: https://github.com/coreos/etcd/blob/master/etcdserver/etcdserverpb/rpc.proto

Documentation/learning/api_guarantees.md

@@ -1,4 +1,4 @@
-# KV API Guarantees
+# KV API guarantees
 
 etcd is a consistent and durable key value store with mini-transaction(TODO: link to txn doc when we have it) support. The key value store is exposed through the KV APIs. etcd tries to ensure the strongest consistency and durability guarantees for a distributed system. This specification enumerates the KV API guarantees made by etcd.
 
@@ -13,17 +13,17 @@ etcd is a consistent and durable key value store with mini-transaction(TODO: lin
 * Combination (read-modify-write) APIs
     * txn
 
-### etcd Specific Definitions
+### etcd specific definitions
 
-#### operation completed
+#### Operation completed
 
 An etcd operation is considered complete when it is committed through consensus, and therefore “executed” -- permanently stored -- by the etcd storage engine. The client knows an operation is completed when it receives a response from the etcd server. Note that the client may be uncertain about the status of an operation if it times out, or there is a network disruption between the client and the etcd member. etcd may also abort operations when there is a leader election. etcd does not send `abort` responses to  clients’ outstanding requests in this event.
 
-#### revision
+#### Revision
 
 An etcd operation that modifies the key value store is assigned with a single increasing revision. A transaction operation might modifies the key value store multiple times, but only one revision is assigned. The revision attribute of a key value pair that modified by the operation has the same value as the revision of the operation. The revision can be used as a logical clock for key value store. A key value pair that has a larger revision is modified after a key value pair with a smaller revision. Two key value pairs that have the same revision are modified by an operation "concurrently".
 
-### Guarantees Provided
+### Guarantees provided
 
 #### Atomicity
 
@@ -60,4 +60,4 @@ etcd ensures linearizability for all other operations by default. Linearizabilit
 [seq_consistency]: https://en.wikipedia.org/wiki/Consistency_model#Sequential_consistency
 [strict_consistency]: https://en.wikipedia.org/wiki/Consistency_model#Strict_consistency
 [serializable_isolation]: https://en.wikipedia.org/wiki/Isolation_(database_systems)#Serializable
-[Linearizability]: #Linearizability
+[Linearizability]: #Linearizability

Documentation/learning/data_model.md

@@ -1,10 +1,10 @@
-# Data Model
+# Data model
 
 etcd is designed to reliably store infrequently updated data and provide reliable watch queries. etcd exposes previous versions of key-value pairs to support inexpensive snapshots and watch history events (“time travel queries”). A persistent, multi-version, concurrency-control data model is a good fit for these use cases.
 
 etcd stores data in a multiversion [persistent][persistent-ds] key-value store. The persistent key-value store preserves the previous version of a key-value pair when its value is superseded with new data. The key-value store is effectively immutable; its operations do not update the structure in-place, but instead always generates a new updated structure. All past versions of keys are still accessible and watchable after modification. To prevent the data store from growing indefinitely over time from maintaining old versions, the store may be compacted to shed the oldest versions of superseded data.
 
-### Logical View
+### Logical view
 
 The store’s logical view is a flat binary key space. The key space has a lexically sorted index on byte string keys so range queries are inexpensive.
 
@@ -12,7 +12,7 @@ The key space maintains multiple revisions. Each atomic mutative operation (e.g.
 
 A key’s lifetime spans a generation. Each key may have one or multiple generations. Creating a key increments the generation of that key, starting at 1 if the key never existed. Deleting a key generates a key tombstone, concluding the key’s current generation. Each modification of a key creates a new version of the key. Once a compaction happens, any generation ended before the given revision will be removed and values set before the compaction revision except the latest one will be removed.
 
-### Physical View
+### Physical view
 
 etcd stores the physical data as key-value pairs in a persistent [b+tree][b+tree]. Each revision of the store’s state only contains the delta from its previous revision to be efficient. A single revision may correspond to multiple keys in the tree. 
 
@@ -22,4 +22,4 @@ etcd also keeps a secondary in-memory [btree][btree] index to speed up range que
 
 [persistent-ds]: https://en.wikipedia.org/wiki/Persistent_data_structure
 [btree]: https://en.wikipedia.org/wiki/B-tree
-[b+tree]: https://en.wikipedia.org/wiki/B%2B_tree
+[b+tree]: https://en.wikipedia.org/wiki/B%2B_tree

Documentation/libraries-and-tools.md

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

Documentation/metrics.md

@@ -14,7 +14,7 @@ The metrics under the `etcd` prefix are for monitoring and alerting. They are st
 
 Metrics that are etcd2 related are documented [v2 metrics guide][v2-http-metrics].
 
-### server
+### Server
 
 These metrics describe the status of the etcd server. In order to detect outages or problems for troubleshooting, the server metrics of every production etcd cluster should be closely monitored.
 
@@ -43,7 +43,7 @@ is totally unavailable.
 
 `proposals_failed_total` are normally related to two issues: temporary failures related to a leader election or longer downtime caused by a loss of quorum in the cluster.
 
-### disk
+### Disk
 
 These metrics describe the status of the disk operations.
 
@@ -60,7 +60,7 @@ A `backend_commit` is called when etcd commits an incremental snapshot of its mo
 
 High disk operation latencies (`wal_fsync_duration_seconds` or `backend_commit_duration_seconds`) often indicate disk issues. It may cause high request latency or make the cluster unstable.
 
-### network
+### Network
 
 These metrics describe the status of the network.
 
@@ -110,7 +110,7 @@ Example Prometheus queries that may be useful from these metrics (across all etc
 The metrics under the `etcd_debugging` prefix are for debugging. They are very implementation dependent and volatile. They might be changed or removed without any warning in new etcd releases. Some of the metrics might be moved to the `etcd` prefix when they become more stable.
 
 
-### snapshot
+### Snapshot
 
 | Name                                       | Description                                                | Type      |
 |--------------------------------------------|------------------------------------------------------------|-----------|

Documentation/op-guide/clustering.md

@@ -76,7 +76,7 @@ The command line parameters starting with `--initial-cluster` will be ignored on
 
 etcd supports encrypted communication through the TLS protocol. TLS channels can be used for encrypted internal cluster communication between peers as well as encrypted client traffic. This section provides examples for setting up a cluster with peer and client TLS. Additional information detailing etcd's TLS support can be found in the [security guide][security-guide].
 
-#### Self-signed sertificates
+#### Self-signed certificates
 
 A cluster using self-signed certificates both encrypts traffic and authenticates its connections. To start a cluster with self-signed certificates, each cluster member should have a unique key pair (`member.crt`, `member.key`) signed by a shared cluster CA certificate (`ca.crt`) for both peer connections and client connections. Certificates may be generated by following the etcd [TLS setup][tls-setup] example.
 
@@ -162,7 +162,7 @@ $ etcd --name infra2 --initial-advertise-peer-urls https://10.0.1.12:2380 \
   --peer-auto-tls
 ```
 
-### Error Cases
+### Error cases
 
 In the following example, 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.
 
@@ -212,17 +212,17 @@ There two methods that can be used for discovery:
 * etcd discovery service
 * DNS SRV records
 
-### etcd Discovery
+### etcd discovery
 
 To better understand the design about discovery service protocol, we suggest reading the discovery service protocol [documentation][discovery-proto].
 
-#### Lifetime of a Discovery URL
+#### Lifetime of a discovery URL
 
 A discovery URL identifies a unique etcd cluster. Instead of reusing a discovery URL, always create discovery URLs for new clusters.
 
 Moreover, discovery URLs should ONLY be used for the initial bootstrapping of a cluster. To change cluster membership after the cluster is already running, see the [runtime reconfiguration][runtime-conf] guide.
 
-#### Custom etcd Discovery Service
+#### Custom etcd discovery service
 
 Discovery uses an existing cluster to bootstrap itself. If using a private etcd cluster, can create a URL like so:
 
@@ -262,7 +262,7 @@ $ etcd --name infra2 --initial-advertise-peer-urls http://10.0.1.12:2380 \
 
 This will cause each member to register itself with the custom etcd discovery service and begin the cluster once all machines have been registered.
 
-#### Public etcd Discovery Service
+#### Public etcd discovery service
 
 If no exiting cluster is available, use the public discovery service hosted at `discovery.etcd.io`.  To create a private discovery URL using the "new" endpoint, use the command:
 
@@ -311,9 +311,9 @@ This will cause each member to register itself with the discovery service and be
 
 Use the environment variable `ETCD_DISCOVERY_PROXY` to cause etcd to use an HTTP proxy to connect to the discovery service.
 
-#### Error and Warning Cases
+#### Error and warning cases
 
-##### Discovery Server Errors
+##### Discovery server errors
 
 
 ```
@@ -339,7 +339,7 @@ $ etcd --name infra0 --initial-advertise-peer-urls http://10.0.1.10:2380 \
 etcdserver: discovery token ignored since a cluster has already been initialized. Valid log found at /var/lib/etcd
 ```
 
-### DNS Discovery
+### DNS discovery
 
 DNS [SRV records][rfc-srv] can be used as a discovery mechanism.
 The `-discovery-srv` flag can be used to set the DNS domain name where the discovery SRV records can be found.

Documentation/op-guide/configuration.md

@@ -1,4 +1,4 @@
-# Configuration Flags
+# Configuration flags
 
 etcd is configurable through command-line flags and environment variables. Options set on the command line take precedence over those from the environment.
 
@@ -8,7 +8,7 @@ The [official etcd ports][iana-ports] are 2379 for client requests and 2380 for
 
 To start etcd automatically using custom settings at startup in Linux, using a [systemd][systemd-intro] unit is highly recommended.
 
-## Member Flags
+## Member flags
 
 ### --name
 + Human-readable name for this member.
@@ -72,7 +72,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 + default: none
 + env variable: ETCD_CORS
 
-## Clustering Flags
+## Clustering flags
 
 `--initial` prefix flags are used in bootstrapping ([static bootstrap][build-cluster], [discovery-service bootstrap][discovery] or [runtime reconfiguration][reconfig]) a new member, and ignored when restarting an existing member.
 
@@ -140,7 +140,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 + default: 0
 + env variable: ETCD_AUTO_COMPACTION_RETENTION
 
-## Proxy Flags
+## Proxy flags
 
 `--proxy` prefix flags configures etcd to run in [proxy mode][proxy]. "proxy" supports v2 API only.
 
@@ -175,7 +175,7 @@ To start etcd automatically using custom settings at startup in Linux, using a [
 + default: 0
 + env variable: ETCD_PROXY_READ_TIMEOUT
 
-## Security Flags
+## Security flags
 
 The security flags help to [build a secure etcd cluster][security].
 
@@ -239,7 +239,7 @@ The security flags help to [build a secure etcd cluster][security].
 + default: false
 + env variable: ETCD_PEER_AUTO_TLS
 
-## Logging Flags
+## Logging flags
 
 ### --debug
 + Drop the default log level to DEBUG for all subpackages.
@@ -252,7 +252,7 @@ The security flags help to [build a secure etcd cluster][security].
 + env variable: ETCD_LOG_PACKAGE_LEVELS
 
 
-## Unsafe Flags
+## Unsafe flags
 
 Please be CAUTIOUS when using unsafe flags because it will break the guarantees given by the consensus protocol.
 For example, it may panic if other members in the cluster are still alive.
@@ -263,7 +263,7 @@ Follow the instructions when using these flags.
 + default: false
 + env variable: ETCD_FORCE_NEW_CLUSTER
 
-## Miscellaneous Flags
+## Miscellaneous flags
 
 ### --version
 + Print the version and exit.

Documentation/op-guide/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.
 
@@ -6,34 +6,34 @@ Reconfiguration requests can only be processed when the majority of the cluster
 
 To better understand the design behind runtime reconfiguration, we suggest reading [the runtime reconfiguration document][runtime-reconf].
 
-## Reconfiguration Use Cases
+## Reconfiguration use cases
 
 Let's walk through some common reasons for reconfiguring a cluster. Most of these just involve combinations of adding or removing a member, which are explained below under [Cluster Reconfiguration Operations][cluster-reconf].
 
-### Cycle or Upgrade Multiple Machines
+### Cycle or upgrade multiple machines
 
 If multiple cluster members need to move due to planned maintenance (hardware upgrades, network downtime, etc.), it is recommended to modify members one at a time.
 
 It is safe to remove the leader, however there is a brief period of downtime while the election process takes place. If the cluster holds more than 50MB, it is recommended to [migrate the member's data directory][member migration].
 
-### Change the Cluster Size
+### Change the cluster size
 
 Increasing the cluster size can enhance [failure tolerance][fault tolerance table] and provide better read performance. Since clients can read from any member, increasing the number of members increases the overall read throughput.
 
 Decreasing the cluster size can improve the write performance of a cluster, with a trade-off of decreased resilience. Writes into the cluster are replicated to a majority of members of the cluster before considered committed. Decreasing the cluster size lowers the majority, and each write is committed more quickly.
 
-### Replace A Failed Machine
+### Replace a failed machine
 
 If a machine fails due to hardware failure, data directory corruption, or some other fatal situation, it should be replaced as soon as possible. Machines that have failed but haven't been removed adversely affect the quorum and reduce the tolerance for an additional failure.
 
 To replace the machine, follow the instructions for [removing the member][remove member] from the cluster, and then [add a new member][add member] in its place. If the cluster holds more than 50MB, it is recommended to [migrate the failed member's data directory][member migration] if it is still accessible.
 
-### Restart Cluster from Majority Failure
+### Restart cluster from majority failure
 
 If the majority of the cluster is lost or all of the nodes have changed IP addresses, then manual action is necessary to recover safely.
 The basic steps in the recovery process include [creating a new cluster using the old data][disaster recovery], forcing a single member to act as the leader, and finally using runtime configuration to [add new members][add member] to this new cluster one at a time.
 
-## Cluster Reconfiguration Operations
+## Cluster reconfiguration operations
 
 Now that we have the use cases in mind, let us lay out the operations involved in each.
 
@@ -52,7 +52,7 @@ To change membership without `etcdctl`, use the [members API][member-api].
 
 TODO: v3 member API documentation
 
-### Update a Member
+### Update a member
 
 #### Update advertise client URLs
 
@@ -83,7 +83,7 @@ $ etcdctl member update a8266ecf031671f3 http://10.0.1.10:2380
 Updated member with ID a8266ecf031671f3 in cluster
 ```
 
-### Remove a Member
+### Remove a member
 
 Let us say the member ID we want to remove is a8266ecf031671f3.
 We then use the `remove` command to perform the removal:
@@ -101,7 +101,7 @@ etcd: this member has been permanently removed from the cluster. Exiting.
 
 It is safe to remove the leader, however the cluster will be inactive while a new leader is elected. This duration is normally the period of election timeout plus the voting process.
 
-### Add a New Member
+### Add a new member
 
 Adding a member is a two step process:
 
@@ -134,7 +134,7 @@ The new member will run as a part of the cluster and immediately begin catching
 If 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 adding 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. This behavior only happens 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 When Adding Members
+#### 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.
@@ -165,7 +165,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/op-guide/runtime-reconf-design.md

@@ -1,4 +1,4 @@
-# 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.
 
@@ -22,7 +22,7 @@ Without the explicit workflow around cluster membership etcd would be vulnerable
 
 We expect runtime reconfiguration to be an infrequent operation. We decided to keep it explicit and user-driven to ensure configuration safety and keep the cluster always running smoothly under explicit 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
 
 With 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 reading the [disaster recovery documentation][disaster-recovery] and prepare for permanent majority lose before putting 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, use runtime reconfiguration API. 
 

Documentation/op-guide/security.md

@@ -1,4 +1,4 @@
-# Security Model
+# Security model
 
 etcd supports automatic TLS as well as authentication through client certificates for both clients to server as well as peer (server to server / cluster) communication.
 
@@ -181,7 +181,7 @@ To disable certificate chain checking, invoke curl with the `-k` flag:
 $ curl -k https://127.0.0.1:2379/v2/keys/foo -Xput -d value=bar -v
 ```
 
-## Notes For etcd Proxy
+## Notes for etcd proxy
 
 etcd proxy terminates the TLS from its client if the connection is secure, and uses proxy's own key/cert specified in `--peer-key-file` and `--peer-cert-file` to communicate with etcd members.
 
@@ -189,7 +189,7 @@ The proxy communicates with etcd members through both the `--advertise-client-ur
 
 When client authentication is enabled for an etcd member, the administrator must ensure that the peer certificate specified in the proxy's `--peer-cert-file` option is valid for that authentication. The proxy's peer certificate must also be valid for peer authentication if peer authentication is enabled.
 
-## Frequently Asked Questions
+## Frequently asked questions
 
 ### I'm seeing a SSLv3 alert handshake failure when using TLS client authentication?
 

Documentation/production-users.md

@@ -1,4 +1,4 @@
-# Production Users
+# Production users
 
 This document tracks people and use cases for etcd in production. By creating a list of production use cases we hope to build a community of advisors that we can reach out to with experience using various etcd applications, operation environments, and cluster sizes. The etcd development team may reach out periodically to check-in on how etcd is working in the field and update this list.
 

Documentation/reporting_bugs.md

@@ -1,4 +1,4 @@
-# Reporting Bugs
+# Reporting bugs
 
 If any part of the etcd project has bugs or documentation mistakes, please let us know by [opening an issue][issue]. We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check that an issue reporting the same problem does not already exist.
 
@@ -18,7 +18,7 @@ It may be worthwhile to read [Elika Etemad’s article on filing good bug report
 
 We might ask for further information to locate a bug. A duplicated bug report will be closed.
 
-## Frequently Asked Questions
+## Frequently asked questions
 
 ### How to get a stack trace
 

Documentation/tuning.md

@@ -4,7 +4,7 @@ The default settings in etcd should work well for installations on a local netwo
 
 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*.
@@ -57,7 +57,7 @@ A complete history works well for lightly used clusters but clusters that are he
 To avoid having a huge log etcd makes periodic snapshots.
 These snapshots provide a way for etcd to compact the log by saving the current state of the system and removing old logs.
 
-### Snapshot Tuning
+### Snapshot tuning
 
 Creating snapshots can be expensive so they're only created after a given number of changes to etcd.
 By default, snapshots will be made after every 10,000 changes.