docs/obs-implementation.rst
author Pierre-Yves David <pierre-yves.david@logilab.fr>
Wed, 25 Jul 2012 19:08:45 +0200
changeset 381 3a161a89d65d
parent 357 b398e9c2dbd1
child 501 9a17c48c2099
permissions -rw-r--r--
obsolete: rely on core to filter extinct changeset out
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     1
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     2
-----------------------------------------------------
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     3
Implementation of Obsolete Marker
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     4
-----------------------------------------------------
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     5
.. warning:: This document is still in heavy work in progress
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
     6
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
     7
Main questions about Obsolete Marker Implementation
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
     8
-----------------------------------------------------
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
     9
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    10
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    11
What data should be contained in a Marker ?
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    12
````````````````````````````````````````````````````
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    13
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    14
There are two critical pieces of information that **must** be stored
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    15
in an obsolete Marker.
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    16
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    17
:object:
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    18
    the old obsoleted changeset
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    19
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    20
:replacements:
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    21
    list of new changeset. list size can be anything, including 0 (0..N)
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    22
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    23
Everybody agreed on this point.
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    24
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    25
 ---
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    26
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    27
This is probably a good idea to have an unique Identifier, for UI, transfer and
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    28
access.
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    29
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    30
    :id: same as changeset but for marker.
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    31
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    32
The field below will depend on the way we exchange obsolete marker between
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    33
changesets.
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    34
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    35
 ---
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    36
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    37
Having audit data will be very useful. When it gets messy you need all the
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    38
information available to understand the situation.
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    39
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    40
I have the feeling that we are versioning history. Therefor we will probably
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    41
need the same kind of information than when versioning Files.
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    42
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    43
:date: date of the marker creation
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    44
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    45
:user: ui.username
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    46
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    47
To go further:
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    48
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    49
:description: "Optional reason for the rewrite (generated by the user)"
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    50
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    51
:tool: the automated tool that made this
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    52
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    53
:operation: Kind of rewritting operation that created the marker (delete,
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    54
            update, split, fold, reordering), to help conflict resolution.
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    55
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    56
Matt said this is "too complicated". I'll wait for him to meet a very hairy
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    57
situation to agree that they are needed.
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    58
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    59
Leaving the door open to any addition data is an option too.
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    60
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    61
How shall we store Marker on disk
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    62
`````````````````````````````````````````````````````````
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    63
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    64
Requirement
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    65
.............
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    66
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    67
We need to quickly load the 'object' to know the "obsolete" set.
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    68
We need quick access by object and replacements to travels along the graph.
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    69
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    70
Common Part
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    71
.............
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    72
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    73
The file is store in `.hg/store/obsmarkers`. It is a binary files:
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    74
247
1a713fa2d3ba change version definition
Pierre-Yves.David@ens-lyon.org
parents: 246
diff changeset
    75
The files starts with a Format Version string
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    76
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    77
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    78
Minimalistic proposal
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    79
.........................
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    80
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    81
The core of a Marker will we stored as:
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    82
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    83
* number of replacement (8-Bytes integer)
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    84
* node id of the obsolete changeset (20-Bytes hash)
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    85
* node id of replacement changeset (20-Bytes hash x number of remplacement)
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    86
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    87
Version with ID
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    88
.........................
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    89
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    90
This version add a node id computed from the marker content. It will be present
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    91
*before* other data:
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    92
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    93
* node id of the maker (20-Bytes hash)
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    94
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    95
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    96
Version with Metadata proposal
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
    97
...............................
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
    98
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
    99
An extra files is used to old metadata (date, user, etc) `.hg/store/obs-extra`:.
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   100
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   101
The format of this field is undefined yet. This will add the following
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   102
field at the end of a marker
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   103
246
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
   104
* offset of the metadata in obs-extra (8-Bytes integer)
1e8e32d3871c doc: idea about OnDisk Storage
Pierre-Yves.David@ens-lyon.org
parents: 244
diff changeset
   105
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   106
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   107
How shall we exchange Marker over the Wire ?
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   108
`````````````````````````````````````````````````````````
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   109
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   110
We can have a lot of markers. We do not want to exchange data for the one we
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   111
already know. Listkey() is not very appropriate there as you get everything.
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   112
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   113
Moreover, we might want to only hear about Marker that impact changeset we are
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   114
pulling.
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   115
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   116
pushkey is not batchable yet (could be fixed)
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   117
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   118
A dedicated discovery and exchange protocol seems mandatory here.
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   119
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   120
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   121
Various technical details
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   122
-----------------------------------------------------
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   123
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   124
Some stuff that worse to note. some may deserve their own section later.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   125
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   126
storing old changeset
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   127
``````````````````````
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   128
244
9d37254031fc [doc] add Question and Answer about Obsolet Marker Implementation
Pierre-Yves.David@ens-lyon.org
parents: 228
diff changeset
   129
The new general delta format allows a very efficient storage of two very similar
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   130
changesets. Storing obsolete children using general delta takes no more place
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   131
than storing the obsolete diff. Reverted file will even we reused. The whole
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   132
operation will take much less space the strip backup.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   133
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   134
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   135
Abstraction from history rewriting UI
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   136
```````````````````````````````````````````
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   137
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   138
How Mercurial handles obsolete marker is independent from what decides
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   139
to create them and what actual operation solves the error case. Any of
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   140
the existing history rewriting UI (rebase, mq, histedit) can lay
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   141
obsolete markers and resolve situation created by others. To go
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   142
further, a hook system of obsolete marker creation would allow each
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   143
mechanism to collaborate with other though a standard and central
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   144
mechanism.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   145
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   146
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   147
Obsolete marker storage
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   148
```````````````````````````
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   149
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   150
The Obsolete marker will most likely be stored outside standard
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   151
history. They are multiple reasons for this:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   152
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   153
First, obsolete markers are really perpendicular to standard history
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   154
there is no strong reason to include it here other than convenience.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   155
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   156
Second, storing obsolete marker inside standard history means:
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   157
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   158
* A changeset must be created every time an obsolete relation is added. Very
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   159
  inconvenient for delete operation.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   160
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   161
* Obsolete marker must be forged at the creation of the new changeset. This
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   162
  is very inconvenient for split operation. And in general it becomes
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   163
  complicated to fix history afterward in particular when working with older
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   164
  clients.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   165
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   166
Storing obsolete marker outside history have several pros:
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   167
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   168
* It eases Exchange of obsolete markers without unnecessary obsolete
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   169
  changeset contents.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   170
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   171
* It allows tuning the actual storage and protocol exchange while maintaining
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   172
  compatibility with older clients through the wire (as we do the repository
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   173
  format).
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   174
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   175
* It eases the exchange of obsolete related information during
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   176
  discovery to exchange obsolete changeset relevant to conflict
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   177
  resolution. Exchanging such information deserves a dedicated
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   178
  protocol.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   179
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   180
Persistent
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   181
```````````````````````
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   182
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   183
*Extinct* changeset and obsolete marker will most likely be garbage collected as
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   184
some point. However, archive server may decide to keep them forever in order to
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   185
keep a fully auditable history in its finest conception.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   186
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   187
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   188
Current status
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   189
-----------------------------------------------------
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   190
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   191
An experimental implementatione exists. What have been done so far.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   192
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   193
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
   194
* 1-1 obsolete marker stored outside history,
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   195
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
   196
* compute obsolete-tip
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
   197
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
   198
* obsolete marker exchange through pushkey,
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   199
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   200
* compute obsolete, unstable, extinct and suspended set.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   201
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   202
* hidden extinct changesets for UI.
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   203
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   204
* Use secret phase to remove from discovery obsolete and unstable changesets (to
228
5a17c0d41a00 proof-read documentation and docstrings
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 227
diff changeset
   205
  be improved soon)
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   206
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   207
* alter rebase to use obsolete markers instead of stripping.
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   208
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   209
* Have an experimental mq-like extension to rewrite history (more on that later)
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   210
357
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   211
* Have an extension to update and mq repository according evolution of
b398e9c2dbd1 doc: English proofreading
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 311
diff changeset
   212
  standard (more on that later)
161
4e3f25ba5401 More doc and index with sphynx
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents:
diff changeset
   213