<commit_before>### Backward Compatibility

The main goal of etcd 2.0 release is to improve cluster safety around bootstrapping and dynamic reconfiguration. To do this, we deprecated the old error-prone APIs and provide a new set of APIs.

The other main focus of this release was a more reliable Raft implementation, but as this change is internal it should not have any notable effects to users.

#### Command Line Flags Changes

The major flag changes are to mostly related to bootstrapping. The `initial-*` flags provide an improved way to specify the required criteria to start the cluster. The advertised URLs now support a list of values instead of a single value, which allows etcd users to gracefully migrate to the new set of IANA-assigned ports (2379/client and 2380/peers) while maintaining backward compatibility with the old ports.

 - `-addr` is replaced by `-advertise-client-urls`.
 - `-bind-addr` is replaced by `-listen-client-urls`.
 - `-peer-addr` is replaced by `-initial-advertise-peer-urls`.
 - `-peer-bind-addr` is replaced by `-listen-peer-urls`.
 - `-peers` is replaced by `-initial-cluster`.
 - `-peers-file` is replaced by `-initial-cluster`.
 - `-peer-heartbeat-interval` is replaced by `-heartbeat-interval`.
 - `-peer-election-timeout` is replaced by `-election-timeout`.

The documentation of new command line flags can be found at
https://github.com/coreos/etcd/blob/master/Documentation/configuration.md.

#### Data Dir
- Default data dir location has changed from {$hostname}.etcd to {name}.etcd.

- The disk format within the data dir has changed. etcd 2.0 should be able to auto upgrade the old data format. Instructions on doing so manually are in the [migration tool doc][migrationtooldoc].

[migrationtooldoc]: ../tools/etcd-migrate/README.md

#### Key-Value API

##### Read consistency flag

The consistent flag for read operations is removed in etcd 2.0.0. The normal read operations provides the same consistency guarantees with the 0.4.6 read operations with consistent flag set.

The read consistency guarantees are:<commit_msg>Documentation: add migration notes to backward compatibility<commit_after>### Backward Compatibility

The main goal of etcd 2.0 release is to improve cluster safety around bootstrapping and dynamic reconfiguration. To do this, we deprecated the old error-prone APIs and provide a new set of APIs.

The other main focus of this release was a more reliable Raft implementation, but as this change is internal it should not have any notable effects to users.

#### Command Line Flags Changes

The major flag changes are to mostly related to bootstrapping. The `initial-*` flags provide an improved way to specify the required criteria to start the cluster. The advertised URLs now support a list of values instead of a single value, which allows etcd users to gracefully migrate to the new set of IANA-assigned ports (2379/client and 2380/peers) while maintaining backward compatibility with the old ports.

 - `-addr` is replaced by `-advertise-client-urls`.
 - `-bind-addr` is replaced by `-listen-client-urls`.
 - `-peer-addr` is replaced by `-initial-advertise-peer-urls`.
 - `-peer-bind-addr` is replaced by `-listen-peer-urls`.
 - `-peers` is replaced by `-initial-cluster`.
 - `-peers-file` is replaced by `-initial-cluster`.
 - `-peer-heartbeat-interval` is replaced by `-heartbeat-interval`.
 - `-peer-election-timeout` is replaced by `-election-timeout`.

The documentation of new command line flags can be found at
https://github.com/coreos/etcd/blob/master/Documentation/configuration.md.

#### Data Directory Naming

The default data dir location has changed from {$hostname}.etcd to {name}.etcd.

#### Data Directory Migration

The disk format within the data directory changed with etcd 2.0.
If you run etcd 2.0 on an etcd 0.4 data directory it will automatically migrate the data and start.
You will want to coordinate this upgrade by walking through each of your machines in the cluster, stopping etcd 0.4 and then starting etcd 2.0.
If you would rather manually do the migration, to test it out first in another environment, you can use the [migration tool doc][migrationtooldoc].

[migrationtooldoc]: ../tools/etcd-migrate/README.md

#### Snapshot Migration

If you are only interested in the data in etcd you can migrate a snapshot of your data from a v0.4.9+ cluster into a new etcd 2.0 cluster using a snapshot migration.
The advantage of this method is that you are directly dumping only the etcd data so you can run your old and new cluster side-by-side, snapshot the data, import it and then point your applications at this cluster.
The disadvantage is that the etcd indexes of your data will change which may confuse applications that use etcd.

To get started get the newest data snapshot from the 0.4.9+ cluster:

```
curl http://cluster.example.com:4001/v2/migration/snapshot > backup.snap
```

Now, import the snapshot into your new cluster:

```
etcdctl -C new_cluster.example.com import --snap backup.snap
```

If you have a large amount of data, you can specify more concurrent works to copy data in parallel by using `-c` flag.
If you have hidden keys to copy, you can use `--hidden` flag to specify.

And the data will quickly copy into the new cluster:

```
entering dir: /
entering dir: /foo
entering dir: /foo/bar
copying key: /foo/bar/1 1
entering dir: /
entering dir: /foo2
entering dir: /foo2/bar2
copying key: /foo2/bar2/2 2
```

#### Key-Value API

##### Read consistency flag

The consistent flag for read operations is removed in etcd 2.0.0. The normal read operations provides the same consistency guarantees with the 0.4.6 read operations with consistent flag set.

The read consistency guarantees are:
{'fraction_non_alphanumeric': 0.0795593635250918, 'fraction_numerical': 0.01154047910473859, 'mean_word_length': 4.0934995547640245, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 4, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3297943', 'n_tokens_mistral': 1594, 'n_tokens_neox': 1534, 'n_words': 787}