API ERRATA -- $Id$

Root Cause of Errata: 
 Library(s) Affected: libsvn_wc
Function(s) Affected: svn_wc_get_pristine_copy_path
     New Behavior in: 1.7
      Related Issues: n/a


== Details of Previous Behavior ==

The function svn_wc_get_pristine_copy_path() returns (via a pointer) the
path where the pristine text of the specified node is stored.  In versions
before 1.7,

  - The returned path is derived purely from the working-copy node path, and
    is always the same for a given working-copy path.

  - Whenever the node has a pristine text, it will exist on disk at that
    path.  Whenever the node has no pristine text, nothing will be found on
    disk at that path.  When the node's pristine state changes, the file at
    the returned path will be added or deleted or replaced with the new
    content.


== Details of New Behavior ==

The function svn_wc_get_pristine_copy_path() still returns (via a pointer)
the path where the pristine text of the specified node is stored, if the
node has a pristine text, or else a path where nothing will be found on
disk, if it does not have one.  From version 1.7,

  - The path remains valid only as long as the node has the same pristine
    text.  After the node's pristine state has changed, the file at that
    path may disappear at any time, and if it still exists it is no longer
    guaranteed to be the correct pristine text for the node.

  - The path may be to a shared file that is simultaneously the pristine
    text file for other nodes that have same pristine text.

  - If the node has no pristine text then the returned path is one where
    there is guaranteed to be nothing on disk but is otherwise arbitrary.


== Rationale for Change ==

Supported uses of this API are:

  - Reading the pristine text from the returned path, immediately.

  - Testing for existence of the returned path, immediately.

Unsupported uses of this API include:

  - Storing the returned path and using it later, after a state change.

  - Writing, deleting, or any kind of modification to the returned path.

The storage of pristine texts has been changed for WC-NG, such that the path
where a given text is stored is now derived from the content of the text
rather than from the path of the node to which it belongs.  Therefore the
returned path can no longer remain valid when the node's pristine state
changes.

Other compatibility behaviours were considered.  One option was to make a
copy of the current pristine text when this API is called and return the
path to that.  That behaviour has difficulties with clean-up.

(###  Before 1.7, were there any cases where the returned path did not
remain valid?  Maybe when revert-base <-> normal-base?  File external?)

The API was already deprecated in version 1.6.


== Impact on API Users ==

Callers that open the returned path for reading, or test for its existence,
immediately after the call or before the node's pristine state changes, are
unaffected.  Callers that do other things may no longer work as expected.