evolve: comparison docs/obs-concept.rst

equal deleted inserted replaced

-:0f1b8119a281
+:706a3a57b567
-==============================
+-----------------------------------------------------------
 Why Do We Need a New Concept
-==============================
+-----------------------------------------------------------
-Current DVCS are great tool to forge a series of flawless changeset on your own.
+Current DVCS are great tools to forge a series of flawless changeset on your own.
-But they perform poorly when is comes to **share** work in progress and
+But they perform poorly when it comes to **sharing** some work in progress and
-**collaborate** on such work in progress.
+**collaborating** on such work in progress.
-When people forge new version of a changeset they create a new changeset and get
+When people forge a new version of a changeset they actually create a
-ride of the original changeset. Difficulties to collaborate mostly came from the
+new changeset and get rid of the original changeset. Difficulties to
-way old content are *removed* from repository.
+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
+With the current version of mercurial, every changeset that exists in
-repository are *visible* and *meaningful*. To get ride of old changeset you
+your repository is *visible* and *meaningful*. To delete old
-rewrote mercurial remove them from the repository storage. with an operation
+(rewritten) changesets, mercurial removes them from the repository
-called *strip*. After the *strip* the repository looks like if the changeset
+storage with an operation called *strip*. After the *stripping*, the
-never existed.
+repository looks like if the changeset never existed.
-This approach is simple and effective but have a very big drawback: You can
+This approach is simple and effective except for one big
-remove changesets from **your repository only**. If strip exists in other
+drawback: you can remove changesets from **your repository only**. If
-repositories it will show of again and again. This only cure for this is to
+a stripped changeset exists in another repository it touches, it will
-strip the offending changeset from all repository. And operation at best
+show up again. This is because a shared changeset becomes
-impractical and in most case impossible!
+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.
 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
+To sum up, the strip approach is very simple but does not handle
-with the outer world. Which is unfortunate for a *Distributed* VCS.
+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
+The Git approach to repository structure is a bit more complex: there
-changesets can exist in a repository. but **only changesets referenced by a git
+can be any amount of unrelated changesets in a repository, and **only
-branch** are *visible* and *meaningful*.
+changesets referenced by a git branch** are *visible* and
+*meaningful*.
 .. warning:: add a schema::
 C
 Only B and A are visible.
 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
-=============================
+-----------------------------------------------------
+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
+Every history rewriting operation stores the information that old rewritten
-changeset is replaced by newer version in a given set of changeset.
+changeset is replaced by newer version in a given set of changesets.
 All basic history rewriting operation can create an appropriate obsolete marker.
 .. figure:: ./figures/example-1-update.*
 To conclude, a single obsolete marker express a relation from **0..n** new
 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
+Finally, the obsolete marker can be **exchanged between
-on mutable part of the history**.
+repositories**. You are able to share the result on your history
+rewriting operations with other prople and **collaborate on the
-Conflicting history rewriting operation can be detected and **resolved** as easily
+mutable part of the history**.
-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
+History rewriting can lead to complex situations. The obsolete marker
-simple representation of this complex reality. But people using complex workflows
+introduces a simple representation for this complex reality. But
-will one day or another have to face the intrinsic complexity of some
+people using complex workflows will one day or another have to face
-situations.
+the intrinsic complexity of some real-world situation.
-This section describes possible situations, defines precise sets of changesets
+This section describes possible situations, defines precise sets of
-involved in such situations and explains how error cases can automatically be
+changesets involved in such situations and explains how the error
-resolved using available information.
+cases can be resolved automatically using the available information.
-obsolete changesets
+Obsolete changesets
--------------------
+````````````````````
 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 rewriting operation.
 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
 history.
-In most cases, the obsolete set will be fully hidden to both UI and discovery so
+In most cases, the obsolete set will be fully hidden to both the UI and
-the user does not have to care about them unless he wants to audit the history rewriting
+discovery, hence users do not have to care about them unless they want to
-operation.
+audit history rewriting operations.
 Unstable changesets
--------------------
+```````````````````
-While exploring the possibilities of the obsolete a bit further, you may end up with
+While exploring the possibilities of the obsolete marker a bit further, you may end up with
-*obsolete* changeset which have *non-obsolete* children. There is two common ways to
+*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**
 .. figure:: ./figures/error-unstable.*
 its parent `A` is *obsolete*. In addition, we have enough data to
 automatically resolve this instability: we know that the new version of `B`
 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
+Proper warnings should be issued when part of the history becomes
-will be able to use the obsolete marker to automatically suggest resolution to
+unstable. The UI will be able to use the obsolete marker to
-the user of even carry them out for him.
+automatically suggest a resolution to the user of even carry them out
+for him.
 XXX details on automatic resolution for
 * movement
 .. [#] 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**.
 * an *obsolete* changeset with *unstable* descendants is called **suspended**.
 have to stay visible and available until their unstable descendant are rewritten
 into stable version.
 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
 different ways.
 .. figure:: ./figures/error-conflicting.*
 Conflicting rewrite of `A` into `A'` and `A''`
-This kind of conflict is easy to detect with obsolete markers, because an obsolete
+This kind of conflict is easy to detect with an obsolete marker
-changeset can have more than one new version. It may be seen as the multiple heads
+because an obsolete changeset can have more than one new version. It
-case which Mercurial warns you about on pull. It is resolved the same way by a merge of
+may be seen as the multiple heads case. Mercurial warns you about this
-A' and A'' that will keep the same parent than `A'` and `A''` with two obsolete
+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
+Allowing multiple new changesets to obsolete a single one allows to
-split changesets from history rewriting conflicts.
+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
 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 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
+* Public changesets are excluded from the obsolete set (public
-never hidden or candidate to garbage collection)
+changesets are never hidden or candidate to garbage collection)
-* *newer* version of public changeset are said **latecomer** and highlighted as
+* *newer* version of a public changeset are called **latecomer** and highlighted as
-error case.
+an error case.
+Solving such an error is easy. Because we know what changeset a
-Solving such error is easy. Because we know what changeset a *latecomer* try to
+*latecomer* tries to rewrite, we can easily compute a smaller
-rewrite, we can easily compute a smaller changeset containing only the change
+changeset containing only the change from the old *public* to the new
-from the old *public* to the new *latecomer*.
+*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
 changesets which tracks the result of history rewriting operations.

changeset 192	706a3a57b567
parent 191	0f1b8119a281
parent 186	0698376bb13c
child 193	adf92ff8d4f6