On Fri, 2009-06-26 at 17:56 +0100, Julian Foad wrote:
> Hi, obliterate fans!
>
> I have been writing[*] a specification of one possible design of
> obliterate, at the level of what transformation occurs to the repository
> as visible from the client side.
>
> The text of the spec is at
> <http://www.foad.me.uk/tmp/obliterate/fspec-cc1/cc1-fspec.txt>
For those of you who, like me, find it easiest to make comments in line,
here is the text in full:
[[[
*******************************************************
* FUNCTIONAL SPECIFICATION FOR ISSUE #516: OBLITERATE *
*******************************************************
TABLE OF CONTENTS
OPEN QUESTIONS
1. INTRODUCTION
1.1 REQUIREMENTS
1.2 CONCEPT
2. THE CORE OBLITERATION OPERATION
2.1 DEFINITION
2.2 DIAGRAMS
2.3 CONSEQUENCES
2.4 ALGEBRA
2.5 EXAMPLES OF USE
3. LOG MESSAGES, WORKING COPIES AND SURROUNDING ISSUES
3.1 LOG MESSAGES AND OTHER REVISION PROPERTIES
3.2 WORKING COPY VALIDITY
3.3 MERGEINFO
4. INVOCATION
4.1 SPECIFYING COMMON KINDS OF OBLITERATION
4.2 THE API
4.3 THE COMMAND_LINE UI
OPEN ISSUES
* Useful parts of ../obliterate-functional-spec.txt
1.
1.1. Use Case Overview
1.2. Current Solution
2.1. Supporting Definitions
2.3. Notes
3. DIFFERENT TYPES OF (CORE) OBLITERATION
3.1. ABSOLUTE vs. VIRTUAL obliteration
3.2. ONLINE vs. OFFLINE vs. REPO-INVALIDATING
5. USE-CASES IN DETAIL
* In a Subversion repository, is a replacement or copy, with the copy-from
source being (the object's natural source path @ REV-1), distinguishable
from a natural continuation of the object's history?
* Add null-change diagrams.
1. INTRODUCTION
This document serves as the functional specification for what's
commonly called the 'svn obliterate' feature.
1.1 REQUIREMENTS
This section summarizes the requirements that this specification aims to
satisfy and any that it explicitly does not aim to satisfy, along with
explanations, restrictions and reasons where appropriate.
The requirements referred to are found in <req-spec.txt>.
REQUIREMENTS SATISFIED
###
REQUIREMENTS NOT SATISFIED
###
1.2 CONCEPT
This section explains the concept of "obliteration" as meant in this
specification.
* Granularity. The granularity of obliteration is a whole change to a
whole node. A whole node means a whole file or a whole directory tree,
including its versioned properties, within a single revision of the
repository. Smaller changes, such as removing a versioned property from
a node, are not supported. A whole change means the change from the
PREVIOUS VERSION to the current version of the node, which could for
example be a replacement by a different kind of node. Obliterating just
part of the change, for example the add part but not the delete part of
the replacement, is not supported.
2. THE CORE OBLITERATION OPERATION
This section deals with how the versioned filesystem in the repository is
transformed by obliteration.
2.1 DEFINITION
This section lists the rules for transforming the repository in order to
obliterate the change made to a specified node-rev.
All unqualified references to the state of the repository are to the state
before the obliteration in question commences.
SUPPORTING DEFINITIONS
* Let the node-rev to be obliterated be called "N". N is either the
repository root node in revision R or is at the path "PARENT/BASENAME" in
revision R, where PARENT is the path of a directory and BASENAME is N's
name as an immediate child of PARENT.
* The node N may be of any kind (file, dir or none) in revision "R".
* PARENT must exist in revision R. (It is not meaningful to obliterate a
(non-existent) node-rev in a non-existent parent unless the obliteration
is simultaneously restoring the parent to existence, and in that case
obliterating the child separately is redundant because obliteration of a
directory is recursive. Operations with a non-existent PARENT are
therefore undefined, for simplicity. ### Is it recursive?)
* Let the node at path (PARENT's copy-from path)/BASENAME in revision
(PARENT's copy-from revision) be called "P", known as the "PREVIOUS
VERSION" of N. Note that P is not necessarily the copy-from source of N.
* The node P may be of any kind (file, dir or none), and is not
necessarily the same kind as N.
RULES OF TRANSFORMATION
* Change the node kind, content and versioned properties of N to those of
P, including cases where N and/or P is non-existent.
* If the new N exists, set its copy-from source to point to P.
* If N exists and P does not, change any nodes that refer to N to "newly
added". If N and P exist, do not change the copy-from source of any
nodes that refer to N, including any succeeding version(s) of N. If N
does not exist and P does, do not change the copy-from source of any
node to refer to it, even if there is a node at N's path in revision
(R+1).
### OR
* If N exists and is not copied from P, in other words if N is added or
replaced with or without history, then replace the copy-from source of
each copy of N with the copy-from source of N. (### My wording here
depends on whether a "replacement" or "copy-from", with source being (the
natural source @ R-1), is distinguishable from a natural continuation.)
* Ensure that no change is made to the node kind, content or versioned
properties of any node-rev in the repository other than N. Note that
this includes nodes that were explicitly or implicitly copied from N.
* Revision properties and other parts of the repository are unchanged by
this transformation.
2.2 DIAGRAMS
Diagrams of the transformations can be seen in the following files:
<http://www.foad.me.uk/tmp/obliterate/fspec-cc1/cc1-dir-ops-4.svg>
<http://www.foad.me.uk/tmp/obliterate/fspec-cc1/cc1-file-ops-4.svg>
in SVG format (readable by Firefox, Inkscape, etc.) or
<http://www.foad.me.uk/tmp/obliterate/fspec-cc1/cc1-dir-ops-4.png>
<http://www.foad.me.uk/tmp/obliterate/fspec-cc1/cc1-file-ops-4.png>
Each file shows the obliteration of a Modification, an Addition, a
Deletion, a Replacement of a single node-rev. Each file also shows the
obliteration of a Move, in which the source and destination nodes at the
same revision are obliterated together.
2.3 CONSEQUENCES
* Obliterating a node-rev N that was an added node (without history) can
result in several unrelated adds of the content of N appearing, where
previously they were copies related by their common ancestor N.
2.4 ALGEBRA
The following statements are derived from the RULES OF TRANSFORMATION.
The notation Ob(N) means obliterate the change at node-rev N. The notation
Ob(N1,N2) means obliterate those changes together, with no meaningful
ordering among them. The notation "Ob(N1),Ob(N2)" means carry out those
obliterations consecutively in the order shown.
* Adjacent revisions can be obliterated in order.
Ob(PATH_at_50, PATH_at_51) == Ob(PATH_at_50),
Ob(PATH_at_51)
### I am not sure this is true.
* Order of revisions matters.
Ob(PATH_at_50), != Ob(PATH_at_51),
Ob(PATH_at_51) Ob(PATH_at_50)
* Siblings are independent.
Ob(PARENT/A_at_50, PARENT/B_at_50) == Ob(PARENT/A_at_50),
Ob(PARENT/B_at_50)
Ob(PARENT/A_at_50), == Ob(PARENT/B_at_50),
Ob(PARENT/B_at_50) == Ob(PARENT/A_at_50)
* Always recursive in a directory.
Ob(PATH_at_50, PARENT/A_at_50) == Ob(PATH_at_50)
* Idempotent.
Ob(PATH_at_50), == Ob(PATH_at_50)
Ob(PATH_at_50)
* Null change.
Ob(PARENT/A_at_50) == no change
where PARENT/A_at_50 is the same as ###
2.5 EXAMPLES OF USE
1. Obliterate a whole revision R.
Operation: Ob(/@R)
Result: Revision R becomes identical to revision (R-1), with log and
diff showing no change between them.
Comments: An alternative expectation is for revision R to no longer
appear in the repository's history. Either a history traversal would
skip over it or later revision numbers would be rewritten. The former
would occur with scheme CC2; the latter is not considered here.
2. Obliterate the whole head revision.
Operation: Ob(/@HEAD)
Result: Revision R (which was and still is HEAD) becomes identical to
revision (R-1). The next revision to be committed will still be (R+1).
Nothing changes in any revision other than R.
Comments: Note that this does not remove the evidence that a commit had
occurred.
3. Obliterate all but the head revision of a file.
Operation: Ob(BIGFILE_at_1, BIGFILE_at_2, ..., BIGFILE_at_HEAD-1)
Result:
Comments:
4. Obliterate one intermediate revision of a file.
Operation: Ob(SECRET_at_50)
Result:
Comments:
3. LOG MESSAGES, WORKING COPIES AND SURROUNDING ISSUES
3.1 LOG MESSAGES AND OTHER REVISION PROPERTIES
This section deals with changes that may be required to log messages and
other revision properties, to stay consistent with the changed history.
* When a change in revision R is obliterated, and the change thereby appears
to be combined into the changes of revision (R+1), the user SHOULD be
given the opportunity to adjust the log messages of both R and (R+1).
Whether any such adjustment is wanted will depend on the nature of the
changes, the details in the log messages, and whether the user wants to
explain or attempt to hide the obliteration.
* When changes in revision R are obliterated, the user MAY be given the
opportunity to adjust any revision properties of revisions R through HEAD.
3.2 WORKING COPY VALIDITY
This section deals with the client-side issues that result from the changed
history.
3.3 MERGEINFO
When a change in revision R is obliterated, the svn:mergeinfo versioned
property may need to be adjusted on revision (R+1) and subsequent revisions
to keep it consistent.
### Not yet known.
4. INVOCATION
This section deals with the way in which a user or administrator carries out
an obliteration. It covers how to specify what should be obliterated, what
happens to log messages, the user interface and the API.
4.1 SPECIFYING COMMON KINDS OF OBLITERATION
4.2 THE API
4.3 THE COMMAND_LINE UI
]]]
> and the diagrams showing the transformation are at
> <http://www.foad.me.uk/tmp/obliterate/fspec-cc1/cc1-dir-ops-4.svg>
> <http://www.foad.me.uk/tmp/obliterate/fspec-cc1/cc1-file-ops-4.svg>
> in SVG format (Firefox, Inkscape, etc.) or
> <http://www.foad.me.uk/tmp/obliterate/fspec-cc1/cc1-dir-ops-4.png>
> <http://www.foad.me.uk/tmp/obliterate/fspec-cc1/cc1-file-ops-4.png>
> in PNG format (web browsers etc.).
>
> This design, which I have designated "CC1" for "Combine-Changes model
> 1", is the one in which obliterating a node-rev means replacing it with
> "what was there before", which means the previous version of it if there
> was one in (REV-1), or nothing if there was nothing in its place in
> (REV-1). The "Combine Changes" name refers what happens to revision (REV
> +1): its content stays the same, which means that the change referred to
> as "-c (REV+1)" becomes the combination of the two old changes "-c
> (REV),(REV+1)".
>
> The interesting bit is to come: how well does this model achieve what
> people want from it, and are there any better alternatives? I haven't
> begun that evaluation.
>
> Any comments, additions and criticism appreciated.
>
> - Julian
>
>
> [*] Full disclosure: I am starting this with a view to getting some
> funding to finish it, so I may have to drop it again some time soon if I
> don't find any funding.
------------------------------------------------------
http://subversion.tigris.org/ds/viewMessage.do?dsForumId=462&dsMessageId=2365782
Received on 2009-06-26 19:00:24 CEST
