*******************************************************
* FUNCTIONAL SPECIFICATION FOR ISSUE #516: OBLITERATE *
*******************************************************

0. TABLE OF CONTENTS

     0. TABLE OF CONTENTS

     1. INTRODUCTION
        1.1. Use Case Overview
        1.2. Current Solution

     2. DEFINITION OF THE OBLITERATION OPERATION
        2.1. Supporting Definitions
        2.2. Main Definition  
        2.3. Notes  

     3. DIFFERENT TYPES OF (CORE) OBLITERATION
        3.1. ABSOLUTE vs. VIRTUAL obliteration
        3.2. ONLINE vs. OFFLINE vs. REPO-INVALIDATING

     4. LIMITATIONS ON THE OBLITERATION SET
        4.1. Obliteration of Deletions (is forbidden)
        4.2. Obliteration of the HEAD revision (is forbidden)
     
     5. USE-CASES IN DETAIL

1. INTRODUCTION

  This document serves as the functional specification for what's 
  commonly called the 'svn obliterate' feature.

  1.1. Use Case Overview

    A. Disable all remote access to confidential information in 
       a repository. [client security]

       a. Description
       
          A user has added information to the repository that should
          not have been made public. The distribution of this
          information must be halted, and where it has been
          distributed, it must be removed.

       b. Examples
       
          User adding documents with confidential information to the
          repository. Distribution to working copies and mirrors needs
          to be stopped ASAP.
            
       c. Primary actor triggering this use case
       
          A key user of the repository that knows what confidential 
          information should be removed, and who can estimate the 
          impact of obliteration (which paths, which revision range(s) 
          etc.
            
          Normal users should not be able to obliterate. For those 
          users we already have 'svn rm'.

    B. Information must be completely removed, both from client access 
       and from access on the server side. [server security]

       a. Description
       
          A user has added information to the repository that should
          not have been made public. The distribution of this
          information must be halted. Additionally, the information
          must be purged from the repository data files themselves,
          either because of the threat of a security breach or because
          the repository itself (or dumps) is publicly distributed.
          
       b. Examples
       
          User adding source code to the repository, finds out later
          that it's infringing certain intellectual rights. All traces
          of the infringing source code, including all derivatives,
          need to be removed from both distribution and from the
          repository itself.

       c. Primary actor triggering this use case

          A key user of the repository that knows what confidential 
          information should be removed, and who can estimate the 
          impact of obliteration (which paths, which revision 
          range(s) etc.

          Normal users should not be able to obliterate. 

    C. Remove obsolete information from a repository and free the 
       associated disc space. [disc space]

       a. Description

          This is the case where unneeded or obsolete information is 
          stored in the repository, taking up lots of disc space. In 
          order to free up disc space, this information may be 
          obliterated.

          This use case typically requires removal of certain subsets
          of the revision history of the repository, while leaving
          later revisions intact. Furthermore, any copies made from an
          obliterated part of the repository to an unobliterated part
          should still be intact.

          This use case is often combined with archiving of the 
          obsolete information: archive first, then obliterate.

       b. Examples
       
          User adding large development tools, binaries or
          external libraries to the product by mistake.

          Users managing huge files (MB/GB's) as part of their 
          normal workflow. These files can be removed when work on 
          newer versions has started.

          Users adding source code, assets and build deliverables 
          in the same repository. Certain assets or build 
          deliverables can be removed

          When a project is moved to its own repository, the 
          project's files may be obliterated from the original 
          repository. This includes moving old projects to an 
          archive repository.
          
          Repositories setup to store product deliverables. Those 
          deliverables for old unmaintained versions, like 
          everything older than a revision or date, may be 
          obliterated from the repository.

          Removal of dead branches which changes have and will not 
          be included in the main development line.

       C. Primary actor triggering this use case

          A repository administrator that's concerned about disc space 
          usage. However, only a key user can decide which information 
          may be obliterated.
          
          Normal users should not be able to obliterate. 

  1.2. Current Solution

    A. Dump -> Filter -> Load
    
       Subversion already has a solution in place to completely remove 
       information from a repository. It's a combination of dumping a 
       repository to text format (svnadmin dump), using filters to 
       remove some nodes or revisions from the text (svndumpfilter) 
       and then loading it back into a new repository (svnadmin load).
       
       Where svndumpfilter is used to remove information from a 
       repository, obliterate should cover at least all of its 
       features.

    B. Advantages of current solution

       + svndumpfilter exists today.
       + It has the most basic include and exclude filters built-in.
       + Its functionality is reasonably well understood.

    C. Disadvantages of current solution

       + svndumpfilter has a number of issues (see issue tracker).
       + Filtering options are limited to include or exclude paths
       + No wildcard support...
       + Filtering is based on pathnames, not node based
       + Due to its streamy way of working it has no random access 
         to the source nor target repository, hence it can't rewrite 
         copies or later modifications on filtered files.
       + Uses an intermediate text format and requires filtering the
         whole repository, not only the relevant revisions -> Slow.
       + Requires the extra disc space for the output repository.
       + The svndumpfiler code is not actively maintained.
       + Slow.
       + Requires shell access on repository server or at least access 
         to dump files.

2. DEFINITION OF THE CORE OBLITERATION OPERATION

  This section defines the "core" functionality of the obliteration
  operation in a minimal way. The core functionality defined here 
  can then be used to implement more complicated operations.

  2.1. Supporting Definitions

    An OBLITERATION SET is defined by a list of PATH@REVISON 
    elements (that is, each element is a pair, consisting of a PATH 
    and REVISION). The same PATH can be paired with multiple 
    REVISIONS to form multiple elements and vice versa.
    (Some restrictions are needed for this set, see notes below)

    An ORIGINAL repository is a repository to which an OBLITERATION 
    operation could be applied, but has not (this includes any 
    subversion repository without obliterations).

    A MODIFIED repository is a repository which is identical to the
    ORIGINAL but for which an OBLITERATION SET has been defined and
    an OBLITERATION operation has been applied.

    A REFERENCE repository is a repository for which any checkout
    operation yields the same data as for the MODIFIED repository, but
    no OBLITERATION operation has been applied to it (it has been
    constructed using regular commits).

  2.2. Main Definition  

    The OBLITERATION operation is defined by the following 
    three properties:

    1. If a PATH@REVISION is checked out of the MODIFIED repository,  
       and the PATH@REVISION is NOT in the OBLITERATION SET, the 
       checkout data is identical to what would have been returned 
       if PATH@REVISION had been checked out of the ORIGINAL.
       
    2. If a PATH@REVISION is checked out of the MODIFIED repository,  
       and the PATH@REVISION IS in the OBLITERATION SET, the 
       checkout data is identical to what would have been returned 
       if PATH@REVPRIOR had been checked out of the ORIGINAL, where 
       REVPRIOR is the last revision prior to REVISION for which
       PATH@REVPRIOR is not in the OBLITERATION SET.
       
    3. Any other mechanism through which a user can interact with 
       the repository (diff/merge/copy/commit/svnsync/etc) should work
       consistently. That is, every remote interaction with MODIFIED
       must yield a result indistinguishable from what would happen if
       the same operation were applied to the REFERENCE repository.

  2.3. Notes  

    a. In the text above, "data" refers to the reported existence of 
       the path, the versioned properties that apply to the path, and
       for files, the actual contents of the file.
     
    b. The definition does not state what happens to revision 
       properties (several options are available), and it does not
       state what happens to the reported history of the path (again,
       several options are available).
     
    c. This definition does not state how an obliteration set is 
       constructed to map out each use case. This is intentional, and
       intended to minimize the complexity of the core OBLITERATION
       operation, and break down the assignment into manageable tasks.
       Mappings between use cases and obliteration sets are discussed
       in individual sections below.
     
    d. Implicit in the above is the fact that the core OBLITERATION 
       functionality would not drop empty revisions. This is
       intentional, and intended to minimize the complexity of the
       core OBLITERATION operation, and break down the assignment
       into manageable tasks. The removal of empty revisions can 
       be implemented through a separate pass (and is actually
       implemented already through svndumpfilter).

    e. The hierarchical nature of the path structure of a project 
       unavoidably leads to certain restrictions on the OBLITERATION
       SET. A repository in consistent state has the property that
       whenever a path of the form [PATH/RELATIVEPATH] exists in the
       repository, the parent directory  must also exist.
       
       Thus, a minimal restriction on the OBLITERATION SET is that 
         1) A change that adds [PATH]@REVISION must never be 
            obliterated unless every sub-path change, adding 
            [PATH/RELATIVEPATH]@REVISION, 
            is obliterated at the same time.
         2) A change that deletes [PATH/RELATIVEPATH]@REVISION
            must never be obliterated unless every parent-path 
            change, deleting [PATH]@REVISION, 
            is obliterated at the same time.
    
       The restrictions implied by note (e) are discussed in more 
       detail in section 4.1 of this document.

3. DIFFERENT TYPES OF (CORE) OBLITERATION
  
    At a high level, obliteration can be classified along two
    dimensions. The ABSOLUTE vs. VIRTUAL distinction refers to whether
    obliterated data is removed from disk or merely hidden. The
    OFFLINE vs. ONLINE distinction refers to whether working copies
    can continue to be used after an obliteration operation. The
    dimensions are independent, so "ABSOLUTE ONLINE", "ABSOLUTE
    OFFLINE", "VIRTUAL ONLINE" and "VIRTUAL OFFLINE" are all possible
    (although "VIRTUAL OFFLINE" has little use).

  3.1. ABSOLUTE vs. VIRTUAL obliteration

    a. For an ABSOLUTE obliteration, the repository must be traversed, 
       and all obliterated data expunged totally, recapturing disk
       space and preventing a person with access to the repository
       from retrieving the information.

       ABSOLUTE obliteration is very time-consuming and require a
       complete copy of the repository (in all currently proposed
       implementation methods). However, after a (modified) copy is
       created, it can replace the original relatively quickly.

    b. For a VIRTUAL obliteration, it is enough to mark the
       obliteratied revisions. The server layer will then dynamically
       determine what to return over the RA layer, presenting only the
       modified version to the client.

       Given a repository with VIRTUAL obliterations, ABSOLUTE
       obliteration can be obtained through a svnsync of the
       repository (since svnsync sees the repository only through the
       RA layer). Thus, the obliteration logic would only need to be
       implemented once.

  3.2. ONLINE vs. OFFLINE vs. REPO-INVALIDATING

    a. An ONLINE implementation of obliteration operates in-place on 
       the repository (as seen from clients' point of wiew), and
       allows clients to continue working on the repository while the
       operation takes place. An ONLINE implementation must be save to
       use without disabling repository access (by shutting down
       servers), and will lock the repository for writing only for
       periods comparable to a commit operation.
     
    b. An OFFLINE implementation of obliteration leaves a valid 
       repository intact at the same location as the original one,
       and attempts to allow most clients to continue working with
       the obliterated repository after obliteration. However, the
       repository is taken offline for some period of time, and all
       unrelated repository access must be blocked by shutting down
       server processes.
    
    c. A REPO-INVALIDATING implementation performs obliteration only 
       as it copies the repository to a completely new location. No
       special effort is made to ensure that clients can continue to
       work without a fresh checkout, and any attempts to do so are
       at the users' risk.
     
4. LIMITATIONS ON THE OBLITERATION SET

  4.1. Obliteration of Deletions (is forbidden)
  
    As section 2.3, note e, mentions, consistency requirements for 
    the repository tree place limitations on the OBLITERATION SET
    is to lead to a valid tree layout. These restrictions stem from
    the requirement that any path in the repository be contained
    within a parent directory structure (i.e. ^/path/subpath cannot
    exist in the repo unless ^/path exists as well). 
    
    A MINIMAL restriction on the OBLITERATION SET is that 
    
    1) A change that adds [PATH]@REVISION must never be obliterated 
       unless every sub-path change, adding 
       [PATH/RELATIVEPATH]@REVISION, is obliterated at the same time.
       
    2) A change that deletes [PATH/RELATIVEPATH]@REVISION must never 
       be obliterated unless every parent-path change, deleting 
       [PATH]@REVISION, is obliterated at the same time.

    However, the minimal restriction is not very intuitive, and can
    lead to unexpected results. Thus a wider restriction should be
    placed on obliteration set so that:
    
    1) Deletion operations can NEVER enter an obliteration set.
    
    2) Apart from the restriction described in 1, the inclusion of 
       [PATH]@REVISION in an obliteration set ALWAYS implies the
        inclusion of all [PATH/RELATIVEPATH]@REVISION as well.

  4.2. Obliteration of the HEAD revision  (is forbidden)
  
    The VIRTUAL approach to obliteration is performed by marking
    all revisions in the obliteration set. The server layer then
    filters the repository to reflect the marks when nodes from
    within the obliteration set are requested, but returning original
    data when other notes are requested.
    
    This works well when obliterating older revisions, but not for
    obliterating from HEAD. This can be seen through an example:
    
    svn add foo.txt
    svn commit              [at r1]
    edit foo.txt
    svn ci                  [at r2]
    svn obl foo.txt@0:HEAD  [OBL-SET: foo.txt@1:2]
    svn up                  [at r2, repo empty (foo.txt obliterated)]
    svn add bar.txt
    svn ci                  [at r3]
    svn up                  [at r3, foo.txt and bar.txt both exist]
    
    At this point, foo.txt magically reappears in the repository,
    since all the data still exists, foo.txt has never been deleted,
    and foo.txt@3 is not in the obliteration set. Hence, by the 
    specification, it should not be affected by the obliteration.
    
    Note that extending the obliteration set does not solve the issue:
    
    svn obl foo.txt@0:HEAD [OBL-SET: foo.txt@1:99999999] 
    
    This would imply that foo.txt can never be added again. This is
    not acceptable either.
    
    This issue does not arise with absolute obliteration, since the
    data is really erased, and a fresh addition can be performed.
    However, as this example shows, obliterating from HEAD can 
    lead to confusion, and increases the number of clients that
    find themselves with working copies that seem up-to-date, but
    have been rendered (partially) invalidated.
    
    Therefore, use-cases requiring obliteration from HEAD should
    be converted to a commit transaction, which increments the
    revision number of the HEAD revision, and brings the repository
    into the desired state, coupled with an obliterate action
    working on the set up to OLD-HEAD.
    
    This conversion could either be implemented by the software, or by 
    the user.
    

5. USE-CASES IN DETAIL

  The workflow of the obliterate solution is defined as follows:
  
    1. SELECT the lines of history to obliterate.
    2. DEFINE the obliteration set consistently with the goals.
    3. OBLITERATE all node@rev elements in the obliteration set.


       + In the security use case, hiding confidential information is much more
         time-critical than the final obliteration.
       + Hiding information can be done by a key user, whereas obliteration
         should be done by an administrator with direct repository access.
         Note: while there's certainly a need to have repository administration
         control without requiring shell access to a server, this need is not
         obliterate specific and as such doesn't have to be solved in the scope
         of this solution.
       + Hiding information can be seen as a dry run for final obliteration. It
         allows the key user to analyse the impact of the selected filters,
         hide extra information or recover where needed before committing to
         removing it from the repository.

       Each of these steps are detailed in the following list of functional
       requirements. We'll probably find that the differences in requirements
       needed for each use cases are mainly in step 3 and 4.

       Priorities are one of:      ( MoSCoW )
         + M - MUST have this.
         + S - SHOULD have this if at all possible.
         + C - COULD have this if it does not affect anything else.
         + W - WON'T have this time but WOULD like in the future.

    1. SELECT a modification to obliterate.

       A. Description

          Allow the user to obliterate a single modification from the
          repository. The lowest level of modification we should
          consider is the change to a file or directory committed in a
          specific revision. (Read: no need to support obliterating a
          single line in a document)

          A modification can be selected by:

          + A path name
          + A PEG revision, default is HEAD.
          + A revision (FROM revision equals TO revision)

          This requirement can be seen as a combination of:
          - SELECT a file or directory.
          - LIMIT the range to the selected revision.

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          M - MUST have this.

    2. SELECT a file to obliterate.

       A. Description
          Allow the user to obliterate a file from the repository. The file
          can be selected by:

          + A path name
          + A PEG revision, default is HEAD.

          If the file was copied from another file, we should have the option
          to select either:
          + the copy
          + the file's ancestor

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          M - MUST have this.

    3. SELECT a directory to obliterate

       A. Description
          Allow the user to obliterate a directory, including all its children,
          the whole tree. The directory can be selected by:

          + A path name
          + A PEG revision, default is HEAD.

          If the directory was copied from another directory, we should have
          the option to select either:
          + the copy
          + the directory's ancestor

          Some of the children of the directory might be 'older' than the
          directory itself. This normally happens when the directory was copied
          from another directory (branched, tagged).

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          M - MUST have this.

    4. SELECT all modifications in a revision to obliterate

       A. Description
          Allows the user to obliterate all modifications made in:

          + A revision (FROM revision equals TO revision)

          This is equal to:
          - SELECT the root of the repository.
          - LIMIT the range to the selected revision.

          It should be possible to choose whether or not to obliterate:
          + the log message, author and date properties
          + all other revision properties.

          Obliterating the HEAD revision can be seen as a special case of this
          requirement.

          Note: the revision number itself does not need to removed.

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          SHOULD have this if at all possible.

    5. SELECT multiple modifications, files or directories to obliterate

       A. Description
          Allows the user to obliterate multiple modifications, files or
          directories.

          Modifications can be selected by:
          + A list of PATH@PEGREV's + revisions

          Paths can be selected by:
          + A list of path@PEGREV's.
          + Wildcards: '*.jpg', 'build_*'

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          SHOULD have this if at all possible.

    6. LIMIT the range between FROM and TO revisions or dates.

       A. Description
          Both FROM and TO may be specified in the form of revisions,
          dates or keywords like HEAD.

          This is the most general case, where both FROM revision and TO
          revision can be specified.

          Depending on which SELECT option was chosen, the default LIMITs will
          be different, as detailed in this table, which defines an
          OBLITERATION SET:

          +--------------+---------------------------+---------------+
          | SELECT       | LIMIT FROM rev            | LIMIT TO rev  |
          +--------------+---------------------------+---------------+
          | modification | HEAD                      | HEAD          |
          | file         | creation rev              | HEAD          |
          | directory    | creation rev              | HEAD          |
          | \ children   | creation rev of directory | HEAD          |
          +--------------+---------------------------+---------------+

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          M - MUST have this.

    7. LIMIT the range between PATH CREATION and TO revisions or dates.

       A. Description
          This LIMIT can only be used when SELECTing files or directories, not
          with modifications.

          This is a special case of requirement IV.6., where the FROM revision
          is defined as the revision in which the selected file or directory
          was either:
          - created
          - copied from another file or directory

          Implementation Note: Can this be implemented through a new keyword
          PATH-CREATION and PATH-LAST-COPY revision? This doesn't need to be
          obliterate specific.

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          M - MUST have this.

       E. Workaround
          As it's difficult right now to make the distinction between a copy
          of a directory and a rename, and a directory might be renamed a few
          times after it was copied, we might need to use a PEG revision to
          indicate where the real directory copy revision can be found.

    9. DEFINE: Include all descendants in the obliteration of a file

       A. Description
          This is basically a greedy obliteration, where all places in the
          repository where a file or a modification to a file has propagated
          through copies or later modifications is also obliterated.

          When obliterating a file, the impact of this obliteration should be
          checked in the selected revision range in the repository. Depending
          on the type of modification, actions should be taken. When the file
          is:

          + Added: This is the creation point of the file. Remove the Add
            operation and the content and properties delta.
          + Deleted: Remove the Delete operation.
          + Replaced by TARGET: see Deleted. Will become Copy operation of the
            TARGET.
          + Copied to TARGET (or resurected): delete the Copied operation and
            drop copy-from path and rev.
            Add the TARGET file  in the selection of to be obliterated files,
            using the same limit (revision range) and impact-on-descendants
            option.
          + Moved to TARGET: delete the Copy+Delete operations and drop
            copy-from path and rev.
            Add the TARGET file in the selection of to be obliterated files,
            using the same limit (revision range) and impact-on-descendants
            option.
          + Modified: delete the Modified operation and the delta.
            Add the modification (file-revision) in the selection of to be
            obliterated modifications, using the same limit (revision range)
            and impact-on-descendants option.

          #TODO: what to do when the TO revision is older than HEAD.

       B. Main use case
          security

       C. Primary actor
          key user

       D. Priority
          M - MUST have this

    9. DEFINE: Exclude all descendants from the obliteration of a file

       A. Description
          If the obliterated information is still needed in a later revision in
          the repository, the information will be restored in that later
          revision.

          When obliterating a file, the impact of this obliteration should be
          checked in the selected revision range in the repository. Depending
          on the type of modification, actions should be taken. When the file
          is:

          + Added: This is the creation point of the file. Remove the Add
            operation and the content and properties delta.
          + Deleted: when the file is obliterated earlier, there's nothing to
            Delete anymore. Remove the Delete operation.
          + Replaced by TARGET: see Deleted. Will become Copy operation of the
            replacing file.
          + Copied to TARGET (or resurected): replace the Copy operation with
            Add (drop copy-from path and rev), find the original contents and
            properties of the file at the copy-from revision and use these for
            the new TARGET.
            #TODO: what to do when the Copy was modified in the working copy
                   before committing. #END-TODO
          + Moved to TARGET: is combination of Deleted and Copied. Will become
            Add of the TARGET with the original content and properties.
          + Modified: replace the Modified operation with Add, find the
            original content and properties of the ancestor, apply the delta to
            that content and properties and use the result to recreate the
            file.

          Note: only the first change after the obliterated revision of the
          file should be handled, except for copies of the now obliterated
          revision.
          
          Note: When a file change is obliterated, any file modification are 
          pushed to the next unobliterated revision, to ensure that 
          obliteration has no effect on elements outside the 
          OBLITERATION SET

          Note: When handling a copy from an ancestor (path@PEGREV) which has
          been obliterated, the revision will be changed so that it becomes
          a copy from the most recent unobliterated ancestor.
          
          Example:
            r1: A  iota   "original content\n"
            r2: M  iota   "original content\nextra line\n"
            r3: M  iota   "original content\nextra line\nthird\n"
            r4: D  iota
            r5: A  cp-iota (copy from iota@2)  "original content\nextra line\n"
          
            Here we obliterate iota, range -r 2:2, exclude descendants.
            
            Result:
            r1: A  iota   "original content\n"
            r2: [obliterated]
            r3: M  iota   "original content\nextra line\nthird\n"
            r4: D  iota
            r5: A  cp-iota (copy from iota@1)  "original content\nextra line\n"

          Note: If no unobliterated ancestors exist, the revision will be
          changed so that it becomes a new addition.

          Example:
            r1: A  iota   "original content\n"
            r2: M  iota   "original content\nextra line\n"
            r3: D  iota
            r4: A  cp-iota (copy from iota@1)    "original content\n"

            Here we obliterate iota, range -r 1:1, exclude descendants.

            Result:
            So, r1 will be obliterated, r2 will be rewritten, r3 should be
            ignored. Since r4 is based on the now obliterated r1, it should be
            rewritten as 'A  cp-iota' with the content and properties of iota@1.

            r1: [obliterated]
            r2: A  iota   "original content\nextra line\n"
            r3: D  iota
            r4: A  cp-iota    "original content\n"

          Note for implementation: if at all possible, this should be
          implemented so that we don't need more copies of the information than
          before the obliteration, to avoid increasing the repository size.
          If not possible, this requirement will only make sense for files that
          have never changed or copied.

       B. Main use case
          disc space

       C. Primary actor
          key user

       D. Priority
          M - MUST have this.

    10. DEFINE: Include all descendants in the obliteration of a directory

       A. Description

       B. Main use case
          security

       C. Primary actor
          key user

       D. Priority
          M - MUST have this

    11. DEFINE: Exclude all descendants from the obliteration of a directory

       A. Description
          When obliterating a directory, the impact of this obliteration should
          be checked in the selected revision range in the repository.
          Depending on the type of modification, actions should be taken. When
          the file is:
          #TODO: add effects of directory operations

       B. Main use case
          disc space

       C. Primary actor
          key user

       D. Priority
          M - MUST have this.

    12. DEFINE: Include all descendants in the obliteration of a modification

       A. Description
          Now that Subversion 1.5 includes merge tracking we have the option to
          find out how modifications cascade through the repository with
          merge operations.

#IMPL-DETAIL
          A merge operation is identified by a change of type Modification
          that includes a change to the svn:mergeinfo property.
#END-OF-IMPL-DETAIL

          When obliterating a modification, the impact of this obliteration
          should be checked in the selected revision range in the repository.
          Depending on the type of modification, actions should be taken.

          When the modification is:
          + Deleted:
          + Replaced by TARGET:
          + Copied to TARGET:
          + Moved to TARGET:
          + Merged to TARGET:
          + Modified:
          + Merged to TARGET:
       #TODO: define how to select descendants.

       B. Main use case
          security

       C. Primary actor
          key user

       D. Priority
          C - COULD have this if it does not affect anything else.

    13. DEFINE: Exclude all descendants from the obliteration of a modification

       A. Description
          If the obliterated modification is still needed in a later revision
          in the repository, that modification will be made available in that
          later revision.

          When obliterating a modification, the impact of this obliteration
          should be checked in the selected revision range in the repository.
          Depending on the type of modification, actions should be taken.

          + Deleted: The inclusion of deletions in an OBLITERATION SET results
            in a number of special issues that need to be handled to ensure 
            that the internal consistency of the reposotory is maintained.
            These issues are covered in detail in the section on 
            "Obliterating Deletions"
          + Replaced by TARGET: Can be ignored.
          + Copied to TARGET:
          + Moved to TARGET:
          + Merged to TARGET: the modification is merged to another file. This
            action can be ignored because when merging a delta to another path,
            that delta is copied and reapplied to the new path, not relying on
            the content of the original delta.
            #TODO: is that true for both FSFS and BDB? Are we not relying on an
            implementation detail that can change in the future?
          + Modified: If the modification contains lines that were modified or
            added in the now obliterated delta, find the original content and
            properties of the ancestor, apply the delta to that content and
            properties and use the result to recreate the file.
          #TODO: define how to select descendants.

       B. Main use case
          disc space

       C. Primary actor
          key user

       D. Priority
          M - MUST have this.

    14. LOG selected modifications, files, directories and revisions

       A. Description
          This is essentially a dry run of the obliterate action. In order to
          assess the impact of the selected filters, the user wants to see the
          list of to-be obliterated paths first.

          The result should be printed to the console and contain the info as
          shown in this example:

          +-----------------------------------------------+-------------------+
          | Revision | Current action | Path              | New action        |
          |          |                |                   | after obliteration|
          +----------+----------------+-------------------+-------------------+
          | r100     | A              | /trunk/SECRET     | [obliterated]     |
          | r101     | M              | /trunk/SECRET     | [obliterated]     |
          | r105     | A+             | /branch/1.0/SECRET| A                 |
          +----------+----------------+-------------------+-------------------+

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          S - SHOULD have this if at all possible.


    15. HIDE selected files, directories and revisions

       A. Description
          #TODO

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          S - SHOULD have this if at all possible.

    16. UNHIDE selected files, directories and revisions

       A. Description
          #TODO

       B. Main use case
          all

       C. Primary actor
          key user

       D. Priority
          S - SHOULD have this if at all possible.

    17. Keep audit trail of obliterated information

       A. Description
          #TODO

       B. Main use case
          security

       C. Primary actor
          administrator

       D. Priority
          C - COULD have this if it does not affect anything else.

    18. Propagating obliteration info to working copies

       A. Description
          #TODO

       B. Main use case
          all

       C. Primary actor
          administrator

       D. Priority
          C - COULD have this if it does not affect anything else.

       E. Workaround

    19. Propagating obliteration info to mirrors

       A. Description
          #TODO

       B. Main use case
          security

       C. Primary actor
          administrator

       D. Priority
          C - COULD have this if it does not affect anything else.

       E. Workaround

[..]

V. Detailed non-functional requirements

    1. Authorization for hiding the information
    2. Authorization for restoring the information
    3. Authorization for obliterating information from the repository
    4. Limit repository downtime
    5. Maintain integrity of the repository
    6. Limit temporary disc space
    7. Compatibility with older Subversion clients


[..]

VI. Requirements vs Use Cases

    This table matches the requirements with the use cases. It tries to answer
    two specific questions:

    1. What's the value of a requirement in terms of the use cases?
    2. Which requirements do we need to implement to really solve a specific
       use case.

    +-------------------------------------------------------------------------+
    | Disable all access to confidential information in a repository  ---     |
    | Remove obsolete information from a repository            |      |   \   |
    +----------------------------------------------------------+------+-------+
    +    [ #TODO: fill in when all reqs are defined ]          |   x  |   x   |
    +                                                          |      |   x   |
    +-------------------------------------------------------------------------+


VII. Appendix

    1. Link to external documentation

    [1] Issue 516: https://issues.apache.org/jira/browse/SVN-516
    [2] Karl Fogel's proposal to use the replay API and filters:
        http://svn.haxx.se/dev/archive-2008-04/0687.shtml
    [3] Bob Jenkins's thread about "Auditability": keep log of what has been
        obliterated:
        http://svn.haxx.se/dev/archive-2008-04/0816.shtml
    [4] Users discussing some examples of the need for obliterate:
        http://svn.haxx.se/users/archive-2005-04/0715.shtml


[The corresponding technical specification will be put in another document]