--- a/docs/obs-concept.rst Tue Mar 27 17:29:16 2012 +0200
+++ b/docs/obs-concept.rst Tue Mar 27 18:35:18 2012 +0200
@@ -1,17 +1,17 @@
------------------------------------------------------------
-Why Do We Need a New Concept
------------------------------------------------------------
+==============================
+ Why Do We Need a New Concept
+==============================
Current DVCS are great tool to forge a series of flawless changeset on your own.
-But they perform poorly whe is comes to **share** work in progress and
+But they perform poorly when is comes to **share** work in progress and
**collaborate** on such work in progress.
When people forge new version of a changeset they create a new changeset and get
-ride of the original changeset. Difficultis to collaborate mostly came from the
+ride of the original changeset. Difficulties to collaborate mostly came from the
way old content are *removed* from repository.
Mercurial Approach: Strip
------------------------------------------------------
+=========================
With current version of mercurial, every changesets that exist in your
repository are *visible* and *meaningful*. To get ride of old changeset you
@@ -19,7 +19,7 @@
called *strip*. After the *strip* the repository looks like if the changeset
never existed.
-This approach is simple and effective but have a very big drawnback: You can
+This approach is simple and effective but have a very big drawback: You can
remove changesets from **your repository only**. If strip exists in other
repositories it will show of again and again. This only cure for this is to
strip the offending changeset from all repository. And operation at best
@@ -29,23 +29,22 @@
As consequence, **you can not rewrite something once you exchange it with
others**. The old version will still exists along side the new one [#]_.
-Moreover backup are create stripped changeset in most case. This allow
-restoration of 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.
-
+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 unfortunate for a *Distributed* VCS.
-.. [#] various work around exists but they are work around 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
------------------------------------------------------
+=================================
-Git approach for repository is a bit more complex: They can be any amount of
-changeset can exist in a repository. but **only changesets referenced by a git
+Git approach for repository is a bit more complex: Any number of
+changesets can exist in a repository. but **only changesets referenced by a git
branch** are *visible* and *meaningful*.
@@ -59,51 +58,51 @@
Only B and A are visible.
-This ease the process of getting ride of old changeset. You can just leave them
-in place and move the reference on the new one. You can then propagate those
-change by moving the git-branch on remote host, newer version overwritting the
-older one.
+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 that 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 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 spoke win. This make collaboration on multiple changeset difficult because
-you can't merge concurent update on 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 forced operation where the operator say "Yes I want this to
-replace that. On higly distributed environment user may end with conflicting
-reference with and no proper way to choose.
+Every overwrite is a forced operation where the operator say "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 make user interface more complicated and move through history
-more constrainted.
+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 the ways to move through history.
-Finally, even if all older changeset still exist in the repository acces to them
+Finally, even if all older changeset still exist in the repository, access to them
is still painful.
------------------------------------------------------
-The Obsolete Marker Concept
------------------------------------------------------
+=============================
+ The Obsolete Marker Concept
+=============================
-As None of the concept was powerful enough to embrace the need to safely rewrite
-history, easily share and collaborate on mutable 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 newer version available in a set of changeset.
+Every history rewriting operation stores the information that the old rewritten
+changeset is replaced by newer version in a given set of changeset.
-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.*
@@ -147,16 +146,15 @@
changesets to **1** old changeset.
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 are displayed by the UI.
+First: we can display a **coherent view** of the history graph in which only a
+single version of your changesets are displayed by the UI.
-Second, because obsolete changeset content are still **available**. You can
+Second, because obsolete changeset content is still **available**. You can
* **browse** the content of your obsolete commit,
@@ -173,49 +171,49 @@
Detecting and solving tricky situation
------------------------------------------------------
+======================================
-History rewriting can lead to complex situation. Obsolete marker introduce a
-simple representation this complex reality. But people using complex workflow
-will one day or another you have to face the intrinsics complexity of some
-situation.
+History rewriting can lead to complex situations. Obsolete marker introduce a
+simple representation of this complex reality. But people using complex workflows
+will one day or another have to face the intrinsic complexity of some
+situations.
-This section describe possible situations, define precise set of changesets
-involved in such situation and explains how error case can we automatically
+This section describes possible situations, defines precise sets of changesets
+involved in such situations and explains how error cases can automatically be
resolved using 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 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 case the obsolete set will be fully hidden to both UI and discovery so
-user do not have to care about them unless he wants to audit history rewriting
+In most cases, the obsolete set will be fully hidden to both UI and discovery so
+the user does not have to care about them unless he wants to audit the history rewriting
operation.
Unstable changesets
-```````````````````
+-------------------
-While exploring obsolete marker possibility a bit further you way end up with
-*obsolete* changeset with *non-obsolete* children. There is two common ways to
+While exploring the possibilities of the obsolete a bit further, you may end up with
+*obsolete* changeset 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**
@@ -248,7 +246,7 @@
changeset. See phase help for details.
The two part of the obsolete set
-``````````````````````````````````````
+--------------------------------
The previous section show that it could be two kinds of *obsolete* changeset:
@@ -274,7 +272,7 @@
Conflicting rewriting
-``````````````````````
+---------------------
If people start to concurrently edit the same part of the history they will
likely meet conflicting situation when a changeset have been rewritten in two
@@ -298,7 +296,7 @@
splitted changeset from history rewriting conflict.
Reliable history
-``````````````````````
+----------------
Obsolete marker really help to smooth rewriting operation process. However they
do not change the fact that **you should only rewrite the mutable part of the
@@ -325,7 +323,7 @@
Conclusion
-----------------
+==========
Obsolete marker is a powerful concept that allow mercurial to safely handle
history rewriting operations. It is a new type of relation between Mercurial
@@ -336,7 +334,7 @@
- Very fast history rewriting operations,
-- auditable and reversible history rewritting process,
+- auditable and reversible history rewriting process,
- clean final history,