--- a/docs/instability.rst Thu Jan 24 18:02:00 2013 -0500
+++ b/docs/instability.rst Thu Jan 24 18:05:59 2013 -0500
@@ -12,7 +12,7 @@
XXX starts by talking about getting ride of changeset.
-DVCSes bring two new major concepts to the Version Control Scene:
+DVCSes bring two new major concepts to the version control scene:
* History is organized as a robust DAG,
* History can be rewritten.
@@ -23,13 +23,13 @@
* Full snapshot of the versioned content,
* Reference to the previous full snapshot used to build the new one,
- * A description of the change who lead from the old content to the new old.
+ * A description of the change which leads from the old content to the new content.
-All three elements are to compute a *unique* hash that identify the changeset
+All three elements are used to compute a *unique* hash that identifies the changeset
(with various other metadata). This identification is a key part of DVCS design.
-This is a very useful property because Changing B parent means
-changing B content too. This requires the creation of **another**
+This is a very useful property because changing B's parent means
+changing B's content too. This requires the creation of **another**
changeset, which is semantically good.
.. figure:: ./figures/edit-is-rewrite-step2.svg
@@ -39,30 +39,30 @@
history. I'm calling them *obsolete* changesets.
-But rewriting a changeset with children does not change these
-children's parent! And because children of the rewritten changeset
-still **depend** on the older "dead" version of the changeset with
-can not get rid of this dead version.
+But rewriting a changeset with children does not change the
+children's parents! And because children of the rewritten changeset
+still **depend** on the older "dead" version of the changeset, we
+cannot get rid of this dead version.
::
Schema base, A and A' and B.
I'm calling these children **unstable** because they are based on a
-dead changeset and prevent people to get rid of it.
+dead changeset and prevent people from getting rid of it.
This instability is an **unavoidable consequence** of the strict dependency of
-changeset. History Rewriting history alway need to take it in account and
-provide a way to rewrite the descendant on the new changeset to avoid
-coexistence of the old and new version of a rewritten changeset.
+changesets. Rewriting history always needs to take it into account and
+provide a way to rewrite the descendants of the new changeset to avoid
+coexistence of the old and new versions of a rewritten changeset.
Everybody is working around the issue
------------------------------------------------
-I'm not claiming that rewriting history is impossible. People are successfully
-doing for years. However they all need to work around *instability*. Several
-work around strategy exists.
+I'm not claiming that rewriting history is impossible. People have been successfully
+doing it for years. However they all need to work around *instability*. Several
+workaround strategies exist.
Rewriting all at once
@@ -79,17 +79,17 @@
Schema!
Several Mercurial commands apply it: rebase, collapse, histedit.
-Mercurial also refuses to amend changeset with descendant. The git
-branch design enforces such approach in git too.
+Mercurial also refuses to amend changesets with descendants. The git
+branch design enforces this approach in git too.
-However, DVCS are **Distributed**. This means that you do not control what
-happen outside your repository. Once a changeset have been exchanged *outside*,
+However, DVCS are **distributed**. This means that you do not control what
+happens outside your repository. Once a changeset has been exchanged *outside*,
there is no way to be sure it does not have descendants somewhere else.
Therefore **if you rewrite changeset that exists elsewhere, you can't eradicate
the risk of instability.**
-Do not rewrite exchanged changeset
+Do not rewrite exchanged changesets
```````````````````````````````````
To work around the issue above, Mercurial introduced phases, which
@@ -99,13 +99,13 @@
collaborating on mutable changesets.
In the Git world, they use another approach to prevent instability. By
-convention only a single developper works on a changeset contained in
+convention only a single developer works on a changeset contained in
a named branch. But once again this is a huge blocker for
collaborating. Moreover clueless people **will** mess up social
convention soon or later.
-Loose the DAG robustness
+Lose the DAG robustness
````````````````````````````
The other approach in Mercurial is to keep the mutable part of the
@@ -115,15 +115,15 @@
This allow much more flexible workflow but two major feature are lost in the
process:
-:graceful merge: MQ use plain-patch to store changeset content and patch have
- trouble to apply in changing context. Applying your queue
+:graceful merge: MQ uses plain patch to store changeset contents, which has
+ problems in changing context. Applying your queue
becomes very painful when context changes.
-:easy branching: A quilt queue is by definition a linear queue. Increasing risk
- of conflict
+:easy branching: A quilt queue is by definition a linear queue, increasing risk
+ of conflict.
-It is possible to collaborate over versioned mq! But you are going to
-have a lot of troubles.
+It is possible to collaborate over versioned MQ! But you are going to
+have a lot of trouble.
Ignore conflicts
```````````````````````````````````
@@ -137,28 +137,28 @@
The "One set of mutable changset == One developer" mantra is also a way to work
around conflicting rewriting of changeset. If two different people are able to
-The git branch model allow to overwrite changeset version by another
+The git branch model allows overwriting changeset version by another
one, but it does not care about divergent version. It is the equivalent
of "common ftp" source management for changesets.
Facing The Danger Once And For All
------------------------------------------------
-Above we saw that, the more effort you put to avoid instability, the more option
-you deny. And even most restrictive work flow can't guarantee that instability
+Above we saw that the more effort you put to avoid instability, the more options
+you deny. And even the most restrictive workflow can't guarantee that instability
will never show up!
Obsolete marker can handle the job
```````````````````````````````````
-It is time to provide a full featured solution to deal with
+It is time to provide a full-featured solution to deal with
instability and to stop working around the issue! This is why I
-developing a new feature for mercurial called "Obsolete markers".
+am developing a new feature for Mercurial called "Obsolete markers".
Obsolete markers have two key properties:
-* Any "old" changeset we want to get ride of is **explicitly** marked
- as "obsolete" by history rewriting operation.
+* Any "old" changeset we want to get rid of is **explicitly** marked
+ as "obsolete" by history rewriting operations.
By explicitly marking the obsolete part of the history, we will be able to
easily detect instability situation.
@@ -166,18 +166,18 @@
* Relations between old and new version of changesets are tracked by obsolete
markers.
- By Storing a meta-history of changeset evolution we are able to easily resolve
- instability and edition conflict [#]_ .
+ By storing a meta-history of changeset evolution we are able to easily resolve
+ instability and edit conflicts [#]_ .
-.. [#] edition conflict is another major obstable to collaboration. See the
+.. [#] Edit conflicts is another major obstable to collaboration. See the
section dedicated to obsolete marker for details.
-Improves robustness == improves simplicity
+Improved robustness == improved simplicity
````````````````````````````````````````````````
This proposal should **first** be seen as a safety measure.
-It allow to detect instability as soon as possible
+It allows detecting instability as soon as possible.
::
@@ -190,7 +190,7 @@
outgoing unstable changesets
(use "hg evolve" or force the push)
-And should not not encourage people to create instability
+And it should not not encourage people to create instability.
::