--- a/docs/instability.rst Fri Jul 06 18:43:25 2012 +0200
+++ b/docs/instability.rst Wed Jul 11 13:59:06 2012 -0400
@@ -10,15 +10,14 @@
XXX starts by talking about getting ride of changeset.
-DVCS 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.
-
However, the two concepts are in contradiction:
-To achieve a robust history, three key elements are gathered in *changeset*:
+To achieve a robust history, three key elements are gathered in *changesets*:
* Full snapshot of the versioned content,
* Reference to the previous full snapshot used to build the new one,
@@ -27,9 +26,9 @@
All three elements are to compute a *unique* hash that identify 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 require the creation of **another** changeset which is a good
-semantic.
+This is a very useful property because Changing B parent means
+changing B content too. This requires the creation of **another**
+changeset, which is semantically good.
::
@@ -39,21 +38,22 @@
history. I'm calling them *obsolete* changesets.
-But rewriting a changeset with children does not changes children parent! And
-because children of the rewritten changeset still **depends** on the older
-"dead" version of the changeset with can not get ride of this dead version.
+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.
::
Schema base, A and A' and B.
-I'm calling those children **unstable** because they are based one a dead
-changeset and prevent people to get ride of it.
+I'm calling these children **unstable** because they are based on a
+dead changeset and prevent people to get 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..
+coexistence of the old and new version of a rewritten changeset.
Everybody is working around the issue
@@ -67,19 +67,19 @@
Rewriting all at once
``````````````````````````
-The simplest way to avoid instability is to ensure rewriting operation always
-ends in a stable situation. This is achieve by rewriting all impacted changeset
-at the same time.
+The simplest way to avoid instability is to ensure rewriting
+operations always end in a stable situation. This is achieved by
+rewriting all affected changesets at the same time.
-Rewriting all descendants at the same time than the rewritted of a changeset.
+Rewriting all descendants at the same time when rewriting a changeset.
::
Schema!
-Several Mercurial commands apply it: rebase, collapse, histedit. Mercurial also
-refuse to amend changeset with descendant. The git branch design enforce such
-approach in git too.
+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.
However, DVCS are **Distributed**. This means that you do not control what
@@ -91,23 +91,25 @@
Do not rewrite exchanged changeset
```````````````````````````````````
-To work around the issue above, mercurial introduced phases that prevent you to
-rewrite shared changeset and ensure other can't pull certain changeset from you.
-But this is a very frustrating limitation that prevent you to efficiently share,
-review and collaborate on mutable changeset.
+To work around the issue above, Mercurial introduced phases, which
+prevent you from rewriting shared changesets and ensure others can't
+pull certain changesets from you. But this is a very frustrating
+limitation that prevents you to efficiently sharing, reviewing and
+collaborating on mutable changesets.
-Git world use another approach to prevent instability. By convention only a
-single developper 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.
+In the Git world, they use another approach to prevent instability. By
+convention only a single developper 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
````````````````````````````
-The other approach use in Mercurial is to keep the mutable part of the history
-outside the DVCS constraint. This is the MQ approach of sticking a quilt queue
-over Mercurial.
+The other approach in Mercurial is to keep the mutable part of the
+history outside the DVCS constraint. This is the MQ approach of
+sticking a quilt queue over Mercurial.
This allow much more flexible workflow but two major feature are lost in the
process:
@@ -119,24 +121,24 @@
: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 ahead a lot
-of troubles.
+It is possible to collaborate over versioned mq! But you are going to
+have a lot of troubles.
-.. Ignore conflicts
-.. ```````````````````````````````````
-..
-.. Another ignored issue is conflicting rewritting of the same changeset. If a
-.. changeset is rewritten two times we have two newer version, duplicated history
-.. complicate to merge.
-..
-.. Mercurial work around by
-..
-.. The "One set of mutable changset == One developper" mantra is also a way to work
-.. around conflicting rewritting of changeset. If two different people are able to
-..
-.. The git branch model allow to overwrite changeset version by another one. But it
-.. does not care about divergent version. It is the equilent of "common ftp" source
-.. management for changeset.
+Ignore conflicts
+```````````````````````````````````
+
+Another ignored issue is a conflicting rewrite of the same changeset.
+If a changeset is rewritten two times we have two newer versions,
+and duplicated history is complicated to merge.
+
+Mercurial work around by
+
+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
+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
------------------------------------------------
@@ -148,13 +150,14 @@
Obsolete marker can handle the job
```````````````````````````````````
-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". Obsolete markers have two key properties:
+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".
+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 ride of is **explicitly** marked
+ as "obsolete" by history rewriting operation.
By explicitly marking the obsolete part of the history, we will be able to
easily detect instability situation.
@@ -186,7 +189,7 @@
outgoing unstable changesets
(use "hg stabilize" or force the push)
-And should not not encourage people to create unstability
+And should not not encourage people to create instability
::
@@ -212,7 +215,7 @@
* Focus on what you do:
I do not like the "all at once" model of history rewriting. I'm comfortable
- with unstability and obsolete marker offer all the tool to safely create and
- handle unstability locally.
+ with instability and obsolete marker offer all the tool to safely create and
+ handle instability locally.