Documentation changes to make MDMF the default mutable format, and

undeprecate "mutable=true". refs ticket:2227

Signed-off-by: Daira Hopwood <daira@jacaranda.org>

diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst
index 6b04429a1efb8edd619163010d124f76e256b876..c1bfb65460501ce2cb2cfb3dd6427ebc952bbcf1 100644 (file)
--- a/docs/frontends/webapi.rst
+++ b/docs/frontends/webapi.rst
@@ -396,27 +396,27 @@ Writing/Uploading a File
  specifying a format= argument in the query string. format=MDMF creates an
  MDMF mutable file. format=SDMF creates an SDMF mutable file. format=CHK
  creates an immutable file. The value of the format argument is
- case-insensitive. If no format is specified, the newly-created file will be
- immutable (but see below).
-
- For compatibility with previous versions of Tahoe-LAFS, the web-API will
- also accept a mutable=true argument in the query string. If mutable=true is
- given, then the new file will be mutable, and its format will be the default
- mutable file format, as configured by the [client]mutable.format option of
- tahoe.cfg on the Tahoe-LAFS node hosting the webapi server. Use of
- mutable=true is discouraged; new code should use format= instead of
- mutable=true (unless it needs to be compatible with web-API servers older
- than v1.9.0). If neither format= nor mutable=true are given, the
- newly-created file will be immutable.
-
- This returns the file-cap of the resulting file. If a new file was created
- by this method, the HTTP response code (as dictated by rfc2616) will be set
- to 201 CREATED. If an existing file was replaced or modified, the response
- code will be 200 OK.
+ case-insensitive.
+
+ The web-API also accepts a mutable=true argument in the query string.
+ If mutable=true is given, then the new file will be mutable, and its
+ format will be the default mutable file format, as configured by the
+ [client]mutable.format option of tahoe.cfg on the Tahoe-LAFS node hosting
+ the webapi server.
+
+ If neither format= nor mutable=true are given, the newly-created file
+ will be immutable.
+
+ This method returns the file-cap of the resulting file. If a new file
+ was created, the HTTP response code (as dictated by `RFC2616`_) will be
+ set to 201 CREATED. If an existing file was replaced or modified, the
+ response code will be 200 OK.
 
  Note that the 'curl -T localfile http://127.0.0.1:3456/uri/$DIRCAP/foo.txt'
  command can be used to invoke this operation.
 
+.. _RFC2616: https://tools.ietf.org/html/rfc2616
+
 ``PUT /uri``
 
  This uploads a file, and produces a file-cap for the contents, but does not

diff --git a/docs/specifications/mutable.rst b/docs/specifications/mutable.rst
index 09e25f32e03c2fd5fafc00cd5e4508f14e79ca36..0c8943c145220880aa7525c951441df416a52644 100644 (file)
--- a/docs/specifications/mutable.rst
+++ b/docs/specifications/mutable.rst
@@ -78,7 +78,8 @@ the share format for SDMF could not be used for MDMF, resulting in a larger
 gap between the two implementations (my original intention had been to make
 SDMF a clean subset of MDMF, where any single-segment MDMF file could be
 handled by the old SDMF code). In the fall of 2011, Kevan's code was finally
-integrated, and first made available in the Tahoe-1.9.0 release.
+integrated, and first made available in the Tahoe-LAFS v1.9.0 release.
+
 
 SDMF vs. MDMF
 -------------
@@ -92,20 +93,19 @@ the first segment of data should be delivered faster from a large MDMF file
 than from an SDMF file, although the overall download will then proceed at
 the same rate.
 
-We've decided to make it opt-in for now: mutable files default to
-SDMF format unless explicitly configured to use MDMF, either in ``tahoe.cfg``
+Starting from Tahoe-LAFS v1.11.0, mutable files default to MDMF format
+unless explicitly configured to use SDMF, either in ``tahoe.cfg``
 (see `<configuration.rst>`__) or in the WUI or CLI command that created a
-new mutable file.
+new mutable file. In previous releases, the default was SDMF.
 
 The code can read and modify existing files of either format without user
-intervention. We expect to make MDMF the default in a subsequent release,
-perhaps 2.0.
+intervention.
 
 Which format should you use? SDMF works well for files up to a few MB, and
-can be handled by older versions (Tahoe-1.8.3 and earlier). If you do not
-need to support older clients, want to efficiently work with mutable files,
-and have code which will use Range: headers that make partial reads and
-writes, then MDMF is for you.
+can be handled by older versions (Tahoe-LAFS v1.8.3 and earlier). If you do
+not need to support older clients, want to efficiently work with mutable
+files, and have code which will use Range: headers that make partial reads
+and writes, then MDMF is for you.
 
 
 Consistency vs. Availability

diff --git a/docs/specifications/uri.rst b/docs/specifications/uri.rst
index 9e6d23367f1a7ada8257683738db4aede27fb695..cfe97f3b9e882690e67ffb46447c75950693b6a9 100644 (file)
--- a/docs/specifications/uri.rst
+++ b/docs/specifications/uri.rst
@@ -139,18 +139,21 @@ hash of the public key in the URI. As a result, the data validation is
 limited to confirming that the data retrieved matches *some* data that was
 uploaded in the past, but not _which_ version of that data.
 
-The format of the write-cap for mutable files is::
+The format of the write-cap for mutable files, for SDMF and MDMF files
+respectively, is::
 
  URI:SSK:(writekey):(fingerprint)
+ URI:MDMF:(writekey):(fingerprint)
 
 Where (writekey) is the base32 encoding of the 16-byte AES encryption key
 that is used to encrypt the RSA private key, and (fingerprint) is the base32
 encoded 32-byte SHA-256 hash of the RSA public key. For more details about
 the way these keys are used, please see mutable.rst_.
 
-The format for mutable read-caps is::
+The format for mutable read-caps, for SDMF and MDMF files respectively, is::
 
  URI:SSK-RO:(readkey):(fingerprint)
+ URI:MDMF-RO:(readkey):(fingerprint)
 
 The read-cap is just like the write-cap except it contains the other AES
 encryption key: the one used for encrypting the mutable file's contents. This
@@ -178,11 +181,13 @@ way to interpret the contents of these files. As a result, a directory
 write-cap looks a lot like a mutable-file write-cap::
 
  URI:DIR2:(writekey):(fingerprint)
+ URI:DIR2-MDMF:(writekey):(fingerprint)
 
 Likewise directory read-caps (which provide read-only access to the
 directory) look much like mutable-file read-caps::
 
  URI:DIR2-RO:(readkey):(fingerprint)
+ URI:DIR2-MDMF-RO:(readkey):(fingerprint)
 
 Historical note: the "DIR2" prefix is used because the non-distributed
 dirnodes in earlier Tahoe releases had already claimed the "DIR" prefix.