--- a/docs/obs-concept.rst Wed Mar 28 11:35:53 2012 +0200
+++ b/docs/obs-concept.rst Wed Mar 28 12:50:42 2012 +0200
@@ -1,33 +1,34 @@
-==============================
- 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 when is comes to **share** work in progress and
-**collaborate** on such work in progress.
+Current DVCS are great tools to forge a series of flawless changeset on your own.
+But they perform poorly when it comes to **sharing** some work in progress and
+**collaborating** 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. Difficulties to collaborate mostly came from the
-way old content are *removed* from repository.
+When people forge a new version of a changeset they actually create a
+new changeset and get rid of the original changeset. Difficulties to
+collaborate mostly came from the way old content is *removed* from
+a 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
-rewrote mercurial remove them from the repository storage. with an operation
-called *strip*. After the *strip* the repository looks like if the changeset
-never existed.
+With the current version of mercurial, every changeset that exists in
+your repository is *visible* and *meaningful*. To delete old
+(rewritten) changesets, mercurial removes them from the repository
+storage with an operation called *strip*. After the *stripping*, the
+repository looks like if the changeset never existed.
-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
-impractical and in most case impossible!
-
+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
+part of a shared global history. Stripping a changeset from all
+repositories is at best impractical and in most case impossible!
As consequence, **you can not rewrite something once you exchange it with
-others**. The old version will still exists along side the new one [#]_.
+others**. The old version will still exist along side the new one [#]_.
Moreover stripping changesets creates backup bundles. This allows
restoration of the deleted changesets, but the process is painful.
@@ -35,17 +36,19 @@
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 unfortunate for a *Distributed* VCS.
+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 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: Any number of
-changesets can exist in a repository. but **only changesets referenced by a git
-branch** are *visible* and *meaningful*.
+The Git approach to repository structure is a bit more complex: there
+can be any amount of unrelated changesets in a repository, and **only
+changesets referenced by a git branch** are *visible* and
+*meaningful*.
.. warning:: add a schema::
@@ -60,47 +63,41 @@
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
+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 has a major drawback:
-
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 say "Yes I want this to
+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 core
part of git, which makes the user interface more complicated and
-constrains the ways to move through history.
+constrains moving through history.
-Finally, even if all older changeset still exist in the repository, access to them
+Finally, even if all older changesets still exist in the repository, accesing them
is still painful.
-=============================
- The Obsolete Marker Concept
-=============================
-
-
-
+-----------------------------------------------------
+The Obsolete Marker Concept
+-----------------------------------------------------
-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.
-
-
+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 the old rewritten
-changeset is replaced by newer version in a given set of changeset.
+Every history rewriting operation stores the information that old rewritten
+changeset is replaced by newer version in a given set of changesets.
All basic history rewriting operation can create an appropriate obsolete marker.
@@ -146,45 +143,47 @@
changesets to **1** old changeset.
Basic Usage
-===========
+-----------------------------------------------------
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 in which only a
-single version of your changesets are displayed by the UI.
+single version of your changesets is displayed by the UI.
Second, because obsolete changeset content is still **available**. You can
+you can
- * **browse** the content of your obsolete commit,
+ * **browse** the content of your obsolete commits,
- * **compare** newer and older version of a changeset,
+ * **compare** newer and older versions of a changeset,
- * **restore** content of previously obsolete changeset.
+ * **restore** content of previously obsolete changesets.
-Finally, obsolete marker can be **exchanged between repositories**. You are able to
-share the result on your history rewriting operation with other and **collaborate
-on mutable part of the history**.
+Finally, the obsolete marker can be **exchanged between
+repositories**. You are able to share the result on your history
+rewriting operations with other prople and **collaborate on the
+mutable part of the history**.
-Conflicting history rewriting operation can be detected and **resolved** as easily
-as conflicting changes on file.
+Conflicting history rewriting operation can be detected and
+**resolved** as easily as conflicting changes on a file.
Detecting and solving tricky situations
-======================================
+-----------------------------------------------------
-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.
+History rewriting can lead to complex situations. The obsolete marker
+introduces a simple representation for this complex reality. But
+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, defines precise sets of changesets
-involved in such situations and explains how error cases can automatically be
-resolved using available information.
+This section describes possible situations, defines precise sets of
+changesets involved in such situations and explains how the error
+cases can be resolved automatically using the available information.
-obsolete changesets
--------------------
+Obsolete changesets
+````````````````````
Old changesets left behind by obsolete operation are called **obsolete**.
@@ -199,21 +198,21 @@
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 UI and discovery so
-the user does not have to care about them unless he wants to audit the history rewriting
-operation.
+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 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
+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
- children .
+ children.
*Non-obsolete* changeset based on *obsolete* one are called **unstable**
@@ -228,9 +227,10 @@
parent (`A`) is `A'`, We can deduce that we should rebase `B` on `A'` to get
a stable history again.
-Proper warning should be issued when part of the history become unstable. UI
-will be able to use the obsolete marker to automatically suggest resolution to
-the user of even carry them out for him.
+Proper warnings should be issued when part of the history becomes
+unstable. The UI will be able to use the obsolete marker to
+automatically suggest a resolution to the user of even carry them out
+for him.
XXX details on automatic resolution for
@@ -245,11 +245,11 @@
.. [#] For this to happen one needs to explicitly enable exchange of draft
changesets. See phase help for details.
-The two part of the obsolete set
---------------------------------
+The two parts of the obsolete set
+``````````````````````````````````````
-The previous section show that there can be two kinds of an *obsolete* changeset:
-
+The previous section shows that there could be two kinds of *obsolete*
+changesets:
* an *obsolete* changeset with no or *obsolete* only descendants is called **extinct**.
@@ -272,7 +272,7 @@
Conflicting rewrites
----------------------
+````````````````````
If people start to concurrently edit the same part of the history they will
likely meet conflicting situations when a changeset has been rewritten in two
@@ -283,20 +283,21 @@
Conflicting rewrite of `A` into `A'` and `A''`
-This kind of conflict is easy to detect with obsolete markers, because an obsolete
-changeset can have more than one new version. It may be seen as the multiple heads
-case which Mercurial warns you about on pull. It is resolved the same way by a merge of
-A' and A'' that will keep the same parent than `A'` and `A''` with two obsolete
+This kind of conflict is easy to detect with an obsolete marker
+because an obsolete changeset can have more than one new version. It
+may be seen as the multiple heads case. Mercurial warns you about this
+on pull. It is resolved the same way by a merge of A' and A'' that
+will keep the same parent than `A'` and `A''` with two obsolete
markers pointing to both `A` and `A'`
.. warning:: TODO: Add a schema of the resolution. (merge A' and A'' with A as
ancestor and graft the result of A^)
-Allowing multiple new changesets to obsolete a single one allows to differenciate
-split changesets from history rewriting conflicts.
+Allowing multiple new changesets to obsolete a single one allows to
+distinguish a split changeset from a history rewriting conflict.
Reliable history
-----------------
+``````````````````````
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
@@ -305,25 +306,24 @@
public changesets, but there are still some corner cases where previously rewritten changesets
are made public.
-Special rules apply for obsolete markers pointing to public changesets
+Special rules apply for obsolete markers pointing to public changesets:
-* Public changesets are excluded from the obsolete set (public changeset are
- never hidden or candidate to garbage collection)
+* Public changesets are excluded from the obsolete set (public
+ changesets are never hidden or candidate to garbage collection)
-* *newer* version of public changeset are said **latecomer** and highlighted as
- error case.
-
+* *newer* version of a public changeset are called **latecomer** and highlighted as
+ an error case.
-Solving such error is easy. Because we know what changeset a *latecomer* try to
-rewrite, we can easily compute a smaller changeset containing only the change
-from the old *public* to the new *latecomer*.
-
+Solving such an error is easy. Because we know what changeset a
+*latecomer* tries to rewrite, we can easily compute a smaller
+changeset containing only the change from the old *public* to the new
+*latecomer*.
.. warning:: add a schema
Conclusion
-==========
+----------------
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