Mercurial > evolve

--- a/docs/obs-concept.rst	Wed Mar 28 11:55:59 2012 +0200
+++ b/docs/obs-concept.rst	Wed Mar 28 13:48:56 2012 +0200
@@ -7,7 +7,7 @@
 **collaborating** on such work in progress.

 When people forge a new version of a changeset they actually create a
-new changeset and get rid of the original changeset. Difficultis to
+new changeset and get rid of the original changeset. Difficulties to
 collaborate mostly came from the way old content is *removed* from
 a repository.

@@ -20,7 +20,7 @@
 storage with an operation called *strip*. After the *stripping*, the
 repository looks like if the changeset never existed.

-This approach is simple and effective except there is a very big
+This approach is simple and effective except for one big
 drawback: you can remove changesets from **your repository only**. If
 a stripped changeset exists in another repository it touches, it will
 show up again. This is because a shared changeset becomes
@@ -30,18 +30,17 @@
 As consequence, **you can not rewrite something once you exchange it with
 others**. The old version will still exist along side the new one [#]_.

-However backups are created while stripping a changeset in most
-cases. This allow restoration of an old changeset but the process is
-painful.
+Moreover stripping changesets creates backup bundles. This allows
+restoration of the deleted changesets, but the process is painful.

-Finally, as the repository format is not optimized for deletion,
-stripping a changeset may be slow in some situation.
+Finally, as the repository format is not optimized for deletion. stripping a
+changeset may be slow in some situations.

 To sum up, the strip approach is very simple but does not handle
 interaction with the outer world, which is very unfortunate for a
 *Distributed* VCS.

-.. [#] various workarounds exist but they are workarounds with their own flow.
+.. [#] various work around exists but they require their own workflows which are distinct from the very elegant basic workflow of Mercurial.

 Git Approach: Overwrite Reference
 -----------------------------------------------------
@@ -62,24 +61,24 @@

     Only B and A are visible.

-This ease the process of getting rid of old changesets. You can just
-leave them in place and move the reference on the new one. You can
-then propagate those changes by moving the git-branch on remote host,
-the newer versions overwritting the older ones.
+This simplifies the process of getting rid of old changesets. You can
+just leave them in place and move the reference on the new one. You
+can then propagate this change by moving the git-branch on remote host
+with the newer version of the marker overwriting the older one.

-This approach goes a bit further but still have a major drawback:
+This approach goes a bit further but still has a major drawback:

-Because you **overwrite** git-branch you have no conflit resolution. The last
-to speak wins. This makes collaboration on multiple changesets difficult because
-you can't merge concurent updates on a changeset.
+Because you **overwrite** the git-branch, you have no conflict resolution. The last
+to act wins. This makes collaboration on multiple changesets difficult because
+you can't merge concurrent updates on a changeset.

-Every overwrite is a forced operation where the operator says "Yes I
-want this to replace that". On a higly distributed environment, a user may
-end with conflicting references and with no proper way to choose.
+Every overwrite is a forced operation where the operator says "Yes I want this to
+replace that. In highly distributed environments, a user may end up with conflicting
+references and no proper way to choose.

-Because of this way to visualize a repository, git-branches are a very
-core part of git. This makes the user interface more complicated and
-moving through history more constrained.
+Because of this way to visualize a repository, git-branches are a core
+part of git, which makes the user interface more complicated and
+constrains moving through history.

 Finally, even if all older changesets still exist in the repository, accesing them
 is still painful.
@@ -90,17 +89,18 @@
 -----------------------------------------------------


-As none of these concepts were powerful enough to embrace the need to
-safely share rewritten history we needed another one.
+As None of the concepts was powerful enough to fulfill the need of safely
+rewriting history, including easy sharing and collaborating on mutable history,
+we needed another one.

 Basic concept
 -----------------------------------------------------


 Every history rewriting operation stores the information that old rewritten
-changesets has a newer version available in a set of changesets.
+changeset is replaced by newer version in a given set of changesets.

-All basic history rewriting operation can create a appropriate obsolete marker.
+All basic history rewriting operation can create an appropriate obsolete marker.


 .. figure:: ./figures/example-1-update.*
@@ -146,21 +146,20 @@
 Basic Usage
 -----------------------------------------------------

-Obsolete markers create a perpendicular history: **a versionned version of the
-changeset graph**. This means that we can have the same feature we have for
+Obsolete markers create a perpendicular history: **a versioned changeset graph**. This means that offers the same features we have for
 versioned files but applied to changeset:

-First: we can display a **coherent view** of the history graph with only a
-single version of your changeset displayed by the UI.
+First: we can display a **coherent view** of the history graph in which only a
+single version of your changesets is displayed by the UI.

-Second, because obsolete changeset contents are still **available**,
+Second, because obsolete changeset content is still **available**. You can
 you can

-    * **browse** the contents of your obsolete commits,
+    * **browse** the content of your obsolete commits,

     * **compare** newer and older versions of a changeset,

-    * **restore** contents of previously obsolete changesets.
+    * **restore** content of previously obsolete changesets.

 Finally, the obsolete marker can be **exchanged between
 repositories**. You are able to share the result on your history
@@ -179,45 +178,44 @@
 people using complex workflows will one day or another have to face
 the intrinsic complexity of some real-world situation.

-This section describes possible situations, define precise sets of
+This section describes possible situations, defines precise sets of
 changesets involved in such situations and explains how the error
-cases can be automatically resolved using available information.
+cases can be resolved automatically using the available information.


 Obsolete changesets
 ````````````````````

-Old changesets left behind by obsolete operation are said **obsolete**.
+Old changesets left behind by obsolete operation are called **obsolete**.

-With the current version of mercurial, this *obsolete* part is
-stripped from the repository before the end of every rewritting
-operation.
+With the current version of mercurial, this *obsolete* part is stripped from the
+repository before the end of every rewriting operation.

 .. figure:: ./figures/error-obsolete.*

     Rebasing `B` and `C` on `A` (as `B'`, `C'`)

     This rebase operation added two obsolete markers from new changesets to old
-    changesets. These Two old changesets are now part of the *obsolete* part of the
+    changesets. These two old changesets are now part of the *obsolete* part of the
     history.

-In most cases the obsolete set will be fully hidden to both the UI and
+In most cases, the obsolete set will be fully hidden to both the UI and
 discovery, hence users do not have to care about them unless they want to
 audit history rewriting operations.

 Unstable changesets
 ```````````````````

-While exploring the obsolete marker possibility a bit further you may
-end up with *obsolete* changeset with *non-obsolete* children. There
-are two common ways to achieve this:
+While exploring the possibilities of the obsolete marker a bit further, you may end up with
+*obsolete* changesets which have *non-obsolete* children. There is two common ways to
+achieve this:

 * Pull a changeset based of an old version of a changeset [#]_.

 * Use a partial rewriting operation. For example amend on a changeset with
-  childrens.
+  children.

-*Non-obsolete* changeset based on *obsolete* one are said **unstable**
+*Non-obsolete* changeset based on *obsolete* one are called **unstable**

 .. figure:: ./figures/error-unstable.*

@@ -236,7 +234,7 @@
 for him.


-XXX details automatic resolution for
+XXX details on automatic resolution for

 * movement

@@ -246,7 +244,7 @@


 .. [#] For this to happen one needs to explicitly enable exchange of draft
-       changeset. See phase help for details.
+       changesets. See phase help for details.

 The two parts of the obsolete set
 ``````````````````````````````````````
@@ -254,9 +252,9 @@
 The previous section shows that there could be two kinds of *obsolete*
 changesets:

-* *obsolete* changeset with no or *obsolete* only descendants, said **extinct**.
+* an *obsolete* changeset with no or *obsolete* only descendants is called **extinct**.

-* *obsolete* changeset with *unstable* descendants, said **suspended**.
+* an *obsolete* changeset with *unstable* descendants is called **suspended**.


 .. figure:: ./figures/error-extinct.*
@@ -269,22 +267,22 @@


 Because nothing outside the obsolete set default on *extinct* changesets, they
-can be safely hidden in the UI and even garbage collected. *Suspended* changeset
-have to stay visible and available until they unstable descendant are rewritten
-in stable version.
+can be safely hidden in the UI and even garbage collected. *Suspended* changesets
+have to stay visible and available until their unstable descendant are rewritten
+into stable version.


-Conflicting rewriting
-``````````````````````
+Conflicting rewrites
+````````````````````

 If people start to concurrently edit the same part of the history they will
-likely meet conflicting situations when a changeset have been rewritten in two
-different versions.
+likely meet conflicting situations when a changeset has been rewritten in two
+different ways.


 .. figure:: ./figures/error-conflicting.*

-    Conflicting rewriting of `A` into `A'` and `A''`
+    Conflicting rewrite of `A` into `A'` and `A''`

 This kind of conflict is easy to detect with an obsolete marker
 because an obsolete changeset can have more than one new version. It
@@ -297,24 +295,24 @@
               ancestor and graft the result of A^)

 Allowing multiple new changesets to obsolete a single one allows to
-distinguish a split changeset from an history rewriting conflict.
+distinguish a split changeset from a history rewriting conflict.

 Reliable history
 ``````````````````````

-Obsolete marker really help to smooth rewriting operation process. However they
+Obsolete marker help to smooth rewriting operation process. However they
 do not change the fact that **you should only rewrite the mutable part of the
-history**. The phase concept enforce this rules by explicitly defining a
-public immutable set of changeset. Rewriting operation refuse to work on
-public changeset, but they is still some corner case where changesets
-rewritten in the past are made public.
+history**. The phase concept enforces this rule by explicitly defining a
+public immutable set of changesets. Rewriting operations refuse to work on
+public changesets, but there are still some corner cases where previously rewritten changesets
+are made public.

-Special rules apply for obsolete marker pointing to public changeset:
+Special rules apply for obsolete markers pointing to public changesets:

 * Public changesets are excluded from the obsolete set (public
   changesets are never hidden or candidate to garbage collection)

-* *newer* version of a public changeset are said **latecomer** and highlighted as
+* *newer* version of a public changeset are called **latecomer** and highlighted as
   an error case.

 Solving such an error is easy. Because we know what changeset a
@@ -328,24 +326,24 @@
 Conclusion
 ----------------

-Obsolete marker is a powerful concept that allows mercurial to safely handle
+The obsolete marker is a powerful concept that allows mercurial to safely handle
 history rewriting operations. It is a new type of relation between Mercurial
-changesets that track the result of history rewriting operations.
+changesets which tracks the result of history rewriting operations.

-This concept is simple to define and provides a very solid base to:
+This concept is simple to define and provides a very solid base for:


 - Very fast history rewriting operations,

-- auditable and reversible history rewritting process,
+- auditable and reversible history rewriting process,

 - clean final history,

-- share and collaborate on mutable part of the history,
+- sharing and collaborating on the mutable part of the history,

-- gracefully handle history rewriting conflict,
+- gracefully handling history rewriting conflicts,

-- allows various history rewriting UI to collaborate with a underlying common API.
+- various history rewriting UI’s collaborating with an underlying common API.

 .. list-table:: Comparison on solution [#]_
    :header-rows: 1