# HG changeset patch # User Pierre-Yves David # Date 1332925635 -7200 # Node ID 135827b4d770c2541c3f1d4820db15c638d073d5 # Parent f047cd4f12358b479ddf77775582c15b0515f5c1# Parent 8907a926954938f429d461bc08b992417bb08f47 merge with backout diff -r 8907a9269549 -r 135827b4d770 docs/obs-concept.rst --- a/docs/obs-concept.rst Tue Mar 27 20:03:59 2012 +0200 +++ b/docs/obs-concept.rst Wed Mar 28 11:07:15 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 when is comes to **share** work in progress and +But they perform poorly whe 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. Difficulties to collaborate mostly came from the +ride of the original changeset. Difficultis 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 drawback: You can +This approach is simple and effective but have a very big drawnback: 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,22 +29,23 @@ 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 stripping changesets creates backup bundles. This allows -restoration of the deleted changesets, but the process is painful. +Moreover backup are create stripped changeset in most case. This allow +restoration of old changeset but the process is painful. Finally, as the repository format is not optimized for deletion. stripping a -changeset may be slow in some situations. +changeset may be slow in some situation. + 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 require their own workflows which are distinct from the very elegant basic workflow of Mercurial. +.. [#] various work around exists but they are work around with their own flow. 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 +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 branch** are *visible* and *meaningful*. @@ -58,51 +59,51 @@ 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 -with the newer version of the marker overwriting the older one. +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 approach goes a bit further but still has a major drawback: +This approach goes a bit further but still have 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. +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. -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. +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. -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. +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. -Finally, even if all older changeset still exist in the repository, access to them +Finally, even if all older changeset still exist in the repository acces to 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 concept was powerful enough to embrace the need to safely rewrite +history, easily share and collaborate 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 +changesets has newer version available in a set of changeset. -All basic history rewriting operation can create an appropriate obsolete marker. +All basic history rewriting operation can create a appropriate obsolete marker. .. figure:: ./figures/example-1-update.* @@ -146,15 +147,16 @@ 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 versionned version of the +changeset graph**. This means that we can have the same feature 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. +First: we can display a **coherent view** of the history graph with only a +single version of your changeset are displayed by the UI. -Second, because obsolete changeset content is still **available**. You can +Second, because obsolete changeset content are still **available**. You can * **browse** the content of your obsolete commit, @@ -170,52 +172,52 @@ as conflicting changes on file. -Detecting and solving tricky situations -====================================== +Detecting and solving tricky 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. +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. -This section describes possible situations, defines precise sets of changesets -involved in such situations and explains how error cases can automatically be +This section describe possible situations, define precise set of changesets +involved in such situation and explains how error case can we automatically resolved using available information. obsolete changesets -------------------- +```````````````````` -Old changesets left behind by obsolete operation are called **obsolete**. +Old changesets left behind by obsolete operation are said **obsolete**. -With the current version of mercurial, this *obsolete* part is stripped from the -repository before the end of every rewriting operation. +With current version of mercurial, this *obsolete* part is stripped from the +repository before the end of every rewritting 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 UI and discovery so -the user does not have to care about them unless he wants to audit the history rewriting +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 operation. 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 obsolete marker possibility a bit further you way end up with +*obsolete* changeset with *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 . + childrens. -*Non-obsolete* changeset based on *obsolete* one are called **unstable** +*Non-obsolete* changeset based on *obsolete* one are said **unstable** .. figure:: ./figures/error-unstable.* @@ -233,7 +235,7 @@ the user of even carry them out for him. -XXX details on automatic resolution for +XXX details automatic resolution for * movement @@ -243,17 +245,17 @@ .. [#] For this to happen one needs to explicitly enable exchange of draft - changesets. See phase help for details. + changeset. See phase help for details. The two part of the obsolete set --------------------------------- +`````````````````````````````````````` -The previous section show that there can be two kinds of an *obsolete* changeset: +The previous section show that it could be two kinds of *obsolete* changeset: -* an *obsolete* changeset with no or *obsolete* only descendants is called **extinct**. +* *obsolete* changeset with no or *obsolete* only descendants, said **extinct**. -* an *obsolete* changeset with *unstable* descendants is called **suspended**. +* *obsolete* changeset with *unstable* descendants, said **suspended**. .. figure:: ./figures/error-extinct.* @@ -266,46 +268,46 @@ Because nothing outside the obsolete set default on *extinct* changesets, they -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. +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. -Conflicting rewrites ---------------------- +Conflicting rewriting +`````````````````````` 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. +likely meet conflicting situation when a changeset have been rewritten in two +different versions. .. figure:: ./figures/error-conflicting.* - Conflicting rewrite of `A` into `A'` and `A''` + Conflicting rewriting 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 +This kind of conflict is easy to detect with obsolete marker because an obsolete +changeset have more than one new version. It may be seen as the multiple heads +case Mercurial warn 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 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 allow to distinct a +splitted changeset from history rewriting conflict. Reliable history ----------------- +`````````````````````` -Obsolete marker help to smooth rewriting operation process. However they +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 -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. +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. -Special rules apply for obsolete markers pointing to public changesets +Special rules apply for obsolete marker pointing to public changeset * Public changesets are excluded from the obsolete set (public changeset are never hidden or candidate to garbage collection) @@ -323,26 +325,26 @@ Conclusion -========== +---------------- -The obsolete marker is a powerful concept that allows mercurial to safely handle +Obsolete marker is a powerful concept that allow 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. +changesets that track the result of history rewriting operations. -This concept is simple to define and provides a very solid base for: +This concept is simple to define and provides a very solid base to: - Very fast history rewriting operations, -- auditable and reversible history rewriting process, +- auditable and reversible history rewritting process, - clean final history, -- sharing and collaborating on the mutable part of the history, +- share and collaborate on mutable part of the history, -- gracefully handling history rewriting conflicts, +- gracefully handle history rewriting conflict, -- various history rewriting UI’s collaborating with an underlying common API. +- allows various history rewriting UI to collaborate with a underlying common API. .. list-table:: Comparison on solution [#]_ :header-rows: 1