--- a/docs/obs-implementation.rst Fri Jul 06 18:43:25 2012 +0200
+++ b/docs/obs-implementation.rst Wed Jul 11 13:59:06 2012 -0400
@@ -11,7 +11,8 @@
What data should be contained in a Marker ?
````````````````````````````````````````````````````
-There is two critical data that **must** be stored in an obsolete Marker.
+There are two critical pieces of information that **must** be stored
+in an obsolete Marker.
:object:
the old obsoleted changeset
@@ -23,21 +24,21 @@
---
-This is probably a good idea to have an unique Identifier, for UI, transfert and
+This is probably a good idea to have an unique Identifier, for UI, transfer and
access.
:id: same as changeset but for marker.
-The field below will depends of the way we exchange obsolete marker betwenn
-changeset.
+The field below will depend on the way we exchange obsolete marker between
+changesets.
---
-Having audit data will be very usefull. When it get messy you need all the
-information you can to understand the situation.
+Having audit data will be very useful. When it gets messy you need all the
+information available to understand the situation.
-I have the felling that we are versionning history. Therefor we will probably
-need the same kind of information than when versionning Files.
+I have the feeling that we are versioning history. Therefor we will probably
+need the same kind of information than when versioning Files.
:date: date of the marker creation
@@ -45,14 +46,14 @@
To go further:
-:description: "Optional reason for the rewrite (generated of added by the user)"
+:description: "Optional reason for the rewrite (generated by the user)"
-:tool: the automated too that made this
+:tool: the automated tool that made this
:operation: Kind of rewritting operation that created the marker (delete,
- update, split, fold, reordering) To help conflict resolution.
+ update, split, fold, reordering), to help conflict resolution.
-Matt see this a "too complicated". I'll wait for him to meet a very hairy
+Matt said this is "too complicated". I'll wait for him to meet a very hairy
situation to agree that they are needed.
Leaving the door open to any addition data is an option too.
@@ -95,8 +96,10 @@
Version with Metadata proposal
...............................
-An extra files is used to old metadata (date, user, etc) `.hg/store/obs-extra`:. The format of this
-field is undefined yet. This will add the following field at the end of a marker
+An extra files is used to old metadata (date, user, etc) `.hg/store/obs-extra`:.
+
+The format of this field is undefined yet. This will add the following
+field at the end of a marker
* offset of the metadata in obs-extra (8-Bytes integer)
@@ -124,7 +127,7 @@
``````````````````````
The new general delta format allows a very efficient storage of two very similar
-changesets. Storing obsolete childrens using general delta takes no more place
+changesets. Storing obsolete children using general delta takes no more place
than storing the obsolete diff. Reverted file will even we reused. The whole
operation will take much less space the strip backup.
@@ -132,53 +135,54 @@
Abstraction from history rewriting UI
```````````````````````````````````````````
-How Mercurial handle obsolete marker is independent from who decide to create
-them and what actual operation solve error case. Any of the existing history
-rewriting UI (rebase, mq, histedit) can lay obsolete marker and resolve
-situation created by other. To go further a hook system of obsolete marker
-creation would allow each mechanism to collaborate with other though a standard
-and central mechanism.
+How Mercurial handles obsolete marker is independent from what decides
+to create them and what actual operation solves the error case. Any of
+the existing history rewriting UI (rebase, mq, histedit) can lay
+obsolete markers and resolve situation created by others. To go
+further, a hook system of obsolete marker creation would allow each
+mechanism to collaborate with other though a standard and central
+mechanism.
Obsolete marker storage
```````````````````````````
-Obsolete marker will most likely be stored outside standard history. They are
-multiple reasons for that:
+The Obsolete marker will most likely be stored outside standard
+history. They are multiple reasons for this:
-
-First, obsolete markers are really perpendicular to standard history there is not
-strong reason to include it here other than convenience.
+First, obsolete markers are really perpendicular to standard history
+there is no strong reason to include it here other than convenience.
Second, storing obsolete marker inside standard history means:
-
* A changeset must be created every time an obsolete relation is added. Very
inconvenient for delete operation.
* Obsolete marker must be forged at the creation of the new changeset. This
- is very inconvenient for split operation. And in general it become
+ is very inconvenient for split operation. And in general it becomes
complicated to fix history afterward in particular when working with older
- client.
+ clients.
-Storing obsolete marker outside history have several pro:
+Storing obsolete marker outside history have several pros:
-* It ease Exchange of obsolete marker without unnecessary obsolete changeset content
+* It eases Exchange of obsolete markers without unnecessary obsolete
+ changeset contents.
-* It allow tuning the actual storage and protocol exchange while maintaining
- compatibility with older client through the wire (as we do the repository
- format)
+* It allows tuning the actual storage and protocol exchange while maintaining
+ compatibility with older clients through the wire (as we do the repository
+ format).
-* ease the exchange of obsolete related information during discovery to exchange
- obsolete changeset relevant to conflict resolution. Exchanging such
- information deserve a dedicated protocol.
+* It eases the exchange of obsolete related information during
+ discovery to exchange obsolete changeset relevant to conflict
+ resolution. Exchanging such information deserves a dedicated
+ protocol.
Persistent
```````````````````````
*Extinct* changeset and obsolete marker will most likely be garbage collected as
some point. However, archive server may decide to keep them forever in order to
-keep a fully auditable history in it's finest conception.
+keep a fully auditable history in its finest conception.
Current status
@@ -197,12 +201,13 @@
* hidden extinct changesets for UI.
-* Use secret phase to remove from discovery obsolete and unstable changeset (to
+* Use secret phase to remove from discovery obsolete and unstable changesets (to
be improved soon)
-* alter rebase to use obsolete marker instead of stripping.
+* alter rebase to use obsolete markers instead of stripping.
* Have an experimental mq-like extension to rewrite history (more on that later)
-* Have an extension to update and mq repository according evolution of standard (more on that later)
+* Have an extension to update and mq repository according evolution of
+ standard (more on that later)