diff -r f86ed5a82723 -r 4da5ecfb5d41 docs/obs-concept.rst --- a/docs/obs-concept.rst Tue Mar 27 18:35:18 2012 +0200 +++ b/docs/obs-concept.rst Tue Mar 27 19:07:20 2012 +0200 @@ -170,7 +170,7 @@ as conflicting changes on file. -Detecting and solving tricky situation +Detecting and solving tricky situations ====================================== History rewriting can lead to complex situations. Obsolete marker introduce a @@ -213,9 +213,9 @@ * 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 said **unstable** +*Non-obsolete* changeset based on *obsolete* one are called **unstable** .. figure:: ./figures/error-unstable.* @@ -233,7 +233,7 @@ the user of even carry them out for him. -XXX details automatic resolution for +XXX details on automatic resolution for * movement @@ -243,17 +243,17 @@ .. [#] For this to happen one needs to explicitly enable exchange of draft - changeset. See phase help for details. + changesets. 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: +The previous section show that there can be two kinds of an *obsolete* changeset: -* *obsolete* changeset with no or *obsolete* only descendants, said **extinct**. +* an *obsolete* changeset with no or *obsolete* only descendants is called **extinct**. -* *obsolete* changeset with *unstable* descendants, said **suspended**. +* an *obsolete* changeset with *unstable* descendants is called **suspended**. .. figure:: ./figures/error-extinct.* @@ -266,46 +266,46 @@ Because nothing outside the obsolete set default on *extinct* changesets, they -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. +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. -Conflicting rewriting +Conflicting rewrites --------------------- 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 -different versions. +likely meet conflicting situations when a changeset has been rewritten in two +different ways. .. figure:: ./figures/error-conflicting.* - Conflicting rewriting of `A` into `A'` and `A''` + Conflicting rewrite of `A` into `A'` and `A''` -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 +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 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 allow to distinct a -splitted changeset from history rewriting conflict. +Allowing multiple new changesets to obsolete a single one allows to differenciate +split changesets from history rewriting conflicts. Reliable history ---------------- -Obsolete marker really help to smooth rewriting operation process. However they +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 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. +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 marker pointing to public changeset +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) @@ -325,11 +325,11 @@ Conclusion ========== -Obsolete marker is a powerful concept that allow mercurial to safely handle +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 that track the result of history rewriting operations. +changesets which tracks the result of history rewriting operations. -This concept is simple to define and provides a very solid base to: +This concept is simple to define and provides a very solid base for: - Very fast history rewriting operations, @@ -338,11 +338,11 @@ - clean final history, -- share and collaborate on mutable part of the history, +- sharing and collaborating on the mutable part of the history, -- gracefully handle history rewriting conflict, +- gracefully handling history rewriting conflicts, -- allows various history rewriting UI to collaborate with a underlying common API. +- various history rewriting UI’s collaborating with an underlying common API. .. list-table:: Comparison on solution [#]_ :header-rows: 1