evolve: comparison docs/obs-concept.rst

equal deleted inserted replaced

-:62de989b2a02
+:b398e9c2dbd1
 -----------------------------------------------------------
 Why Do We Need a New Concept
 -----------------------------------------------------------
-Current DVCS are great tools to forge a series of flawless changeset on your own.
+Current DVCSes are great tools for forging a series of flawless
-But they perform poorly when it comes to **sharing** some work in progress and
+changesets on your own. But they perform poorly when it comes to
-**collaborating** on such work in progress.
+**sharing** some work in progress and **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. Difficulties to
 collaborate mostly came from the way old content is *removed* from
 a repository.
 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.
+repository looks as if the changeset never existed.
 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!
+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 exist along side the new one [#]_.
 Moreover stripping changesets creates backup bundles. This allows
 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.
+.. [#] 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
 -----------------------------------------------------
 The Git approach to repository structure is a bit more complex: there
 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
+Because you **overwrite** the git-branch, you have no conflict
-to act wins. This makes collaboration on multiple changesets difficult because
+resolution. The last to act wins. This makes collaboration on multiple
-you can't merge concurrent updates on a changeset.
+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. In highly distributed environments, a user may end up with conflicting
+Every overwrite is a forced operation where the operator says, "yes I
-references and no proper way to choose.
+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 moving through history.
-Finally, even if all older changesets still exist in the repository, accesing them
+Finally, even if all older changesets still exist in the repository,
-is still painful.
+accesing them is still painful.
 -----------------------------------------------------
 The Obsolete Marker Concept
 -----------------------------------------------------
-As None of the concepts was powerful enough to fulfill the need of safely
+As none of the concepts was powerful enough to fulfill the need of
-rewriting history, including easy sharing and collaborating on mutable history,
+safely rewriting history, including easy sharing and collaboration on
-we needed another one.
+mutable history, we needed another one.
 Basic concept
 -----------------------------------------------------
 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
+Obsolete markers create a perpendicular history: **a versioned
-versioned files but applied to changeset:
+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 is displayed by the UI.
 Second, because obsolete changeset content is still **available**. You can
 .. 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
+This rebase operation added two obsolete markers from new
-changesets. These two old changesets are now part of the *obsolete* part of the
+changesets to old changesets. These two old changesets are now
-history.
+part of the *obsolete* part of the history.
 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 marker a bit further, you may end up with
+While exploring the possibilities of the obsolete marker a bit
-*obsolete* changesets which have *non-obsolete* children. There is two common ways to
+further, you may end up with *obsolete* changesets which have
-achieve this:
+*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.
 .. figure:: ./figures/error-unstable.*
 Amend `A` into `A'` leaving `B` behind.
-In this situation we can not consider `B` as *obsolete*.  But we have all
+In this situation we cannot consider `B` as *obsolete*. But we
-necessary data to detect `B` as an *unstable* branch of the history because
+have all the necessary data to detect `B` as an *unstable* branch
-its parent `A` is *obsolete*. In addition, we have enough data to
+of the history because its parent `A` is *obsolete*. In addition,
-automatically resolve this instability: we know that the new version of `B`
+we have enough data to automatically resolve this instability: we
-parent (`A`) is `A'`, We can deduce that we should rebase `B` on `A'` to get
+know that the new version of `B` parent (`A`) is `A'`. We can
-a stable history again.
+deduce that we should rebase `B` on `A'` to get a stable history
+again.
 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.
+for them.
 XXX details on automatic resolution for
 * movement
 In this example we have two *obsolete* changesets: `C` with no *unstable*
 children is *extinct*. `A` with *unstable* descendant (`B`) is *suspended*.
 `B` is *unstable* as before.
-Because nothing outside the obsolete set default on *extinct* changesets, they
+Because nothing outside the obsolete set default on *extinct*
-can be safely hidden in the UI and even garbage collected. *Suspended* changesets
+changesets, they can be safely hidden in the UI and even garbage
-have to stay visible and available until their unstable descendant are rewritten
+collected. *Suspended* changesets have to stay visible and available
-into stable version.
+until their unstable descendant are rewritten into stable version.
 Conflicting rewrites
 ````````````````````
 distinguish a split changeset from a history rewriting conflict.
 Reliable history
 ``````````````````````
-Obsolete marker help to smooth rewriting operation process. However they
+Obsolete markers help to smooth rewriting operation process. However
-do not change the fact that **you should only rewrite the mutable part of the
+they do not change the fact that **you should only rewrite the mutable
-history**. The phase concept enforces this rule by explicitly defining a
+part of the history**. The phase concept enforces this rule by
-public immutable set of changesets. Rewriting operations refuse to work on
+explicitly defining a public immutable set of changesets. Rewriting
-public changesets, but there are still some corner cases where previously rewritten changesets
+operations refuse to work on public changesets, but there are still
-are made public.
+some corner cases where previously rewritten changesets are made
+public.
 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 called **latecomer** and highlighted as
+* *newer* version of a public changeset are called **latecomer** and
-an error case.
+highlighted as an error case.
 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*.
 - sharing and collaborating on the mutable part of the history,
 - gracefully handling history rewriting conflicts,
-- various history rewriting UI’s collaborating with an underlying common API.
+- various history rewriting UI's collaborating with an underlying common API.
 .. list-table:: Comparison on solution [#]_
 :header-rows: 1
 * - Solution

branch	stable
changeset 357	b398e9c2dbd1
parent 234	d32c07269dcd
child 519	9825c7da5b54