svn commit: r947978 - /subversion/trunk/notes/api-errata/wc007.txt

[ju...@apache.org]

Author: julianfoad
Date: Tue May 25 09:26:52 2010
New Revision: 947978

URL: http://svn.apache.org/viewvc?rev=947978&view=rev
Log:
* notes/api-errata/wc007.txt:  New file.

Added:
    subversion/trunk/notes/api-errata/wc007.txt   (with props)

Added: subversion/trunk/notes/api-errata/wc007.txt
URL: http://svn.apache.org/viewvc/subversion/trunk/notes/api-errata/wc007.txt?rev=947978&view=auto
==============================================================================
--- subversion/trunk/notes/api-errata/wc007.txt (added)
+++ subversion/trunk/notes/api-errata/wc007.txt Tue May 25 09:26:52 2010
@@ -0,0 +1,80 @@
+API ERRATA -- $Id: wc006.txt 943050 2010-05-11 08:56:25Z julianfoad $
+
+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.
+

Propchange: subversion/trunk/notes/api-errata/wc007.txt
------------------------------------------------------------------------------
    svn:mime-type = text/plain