diff docs/instability.rst @ 357:b398e9c2dbd1 stable

doc: English proofreading

--- 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.