Update Deltas and TODO documents.

doc/notes/TODO

@@ -32,6 +32,12 @@
 
 - [ ] Migration tool
 - [ ] Complete header handling
+  - [ ] Accept
+  - [ ] If-None-Match
+  - [ ] If-Modified-Since
+  - [ ] Range
+  - [ ] Limit
+  - [ ] (PUT) Digest
 - [ ] Query API
 
 # Alpha 3 TODO
@@ -48,3 +54,8 @@
 - [ ] AuthN/Z
   - [ ] Authentication
   - [ ] WebAC
+
+# Alpha 5 TODO
+
+- Blank nodes
+- Hash URIs

doc/notes/fcrepo4_deltas.md

@@ -1,24 +1,68 @@
 # Divergencies between lakesuperior and FCREPO4
 
-## Endpoints
+This is a (vastly incomplete) list of discrepancies between the current FCREPO4
+implementation and LAKEsuperior. More will be added as more clients will use
+it.
 
-The FCREPO root endpoint is `/rest`. The LAKEsuperior root endpoint is `/ldp`.
 
-This should not pose a problem if a client does not have `rest` hard-coded in
-its code, but in any event, the `/rest` endpoint is provided for backwards
-compatibility.
+## Not yet implemented (but in the plans)
 
-LAKEsuperior adds the (currently stub) `query` endpoint. Other endpoints for
-non-LDP services may be opened in the future.
+See [TODO](TODO)
+
+- Various header handling
+- Versioning
+- AuthN/Z
+- Fixity check
+- Blank nodes
+- Hash URIs
 
-## Automatic pairtree generation
+
+## Potentially breaking changes
+
+The following  divergences may lead into incompatibilities with some clients.
+
+### Atomicity
+
+FCREPO4 supports batch atomic operations whereas a transaction can be opened
+and a number of operations (i.e. multiple R/W requests to the repository) can
+be performed. The operations are persisted in the repository only if and when
+the transaction is committed.
+
+LAKesuperior only supports atomicity for a single LDP request. I.e. a single
+HTTTP request that should reult in multiple write operations to the storage
+layer is only persisted if no exception is thrown. Otherwise, the operation is
+rolled back in order to prevent resources to be left in an inconsistent state.
+
+### Tombstone methods
+
+If a client requests a tombstone resource in
+FCREPO4 with a method other than DELETE, the server will return `405 Method Not
+Allowed` regardless of whether the tombstone exists or not.
+
+LAKEsuperior will return `405` only if the tombstone actually exists, `404`
+otherwise.
+
+### Web UI
+
+FCREPO4 includes a web UI for simple CRUD operations.
+
+Such a UI is not in the immediate LAKEsuperior development plans. However, a very
+basic UI may at some point be built for read-only interaction (i.e.
+requesting resources and clicking through relationship links). A more complete
+UI should be built for simple and/or SPARQL queries.
+
+
+## Non-standard client breaking changes
+
+The following changes may be incompatible with clients relying on some FCREPO4
+behavior not endorsed by LDP or other specifications.
+
+### Automatic pairtree generation
 
 A `POST` request without a slug in FCREPO4 results in a pairtree consisting of
 several intermediate nodes leading to the automatically minted identifier. E.g.
 
-~~~
-POST /rest
-~~~
+    POST /rest
 
 results in `/rest/8c/9a/07/4e/8c9a074e-dda3-5256-ea30-eec2dd4fcf61` being
 created.
@@ -27,7 +71,7 @@ The same request in LAKEsuperior would create
 `/rest/8c9a074e-dda3-5256-ea30-eec2dd4fcf61` (obviously the identifiers will be
 different).
 
-## Explicit intermediate paths
+### Explicit intermediate paths
 
 In FCREPO4, a PUT request to `/rest/a/b/c`, given `/rest/a` and `rest/a/b` not
 previously existing, results in the creation of Pairtree resources that are
@@ -39,7 +83,38 @@ in LAKEsuperior in a 404.
 In both above cases, PUTting into `rest/a` yields a 409, POSTing to it results
 in a 201.
 
-## Lenient handling
+
+## Deprecation track
+
+LAKEsuperior offers some "legacy" options to replicate the FCREPO4 behavior,
+however encourages new development to use a different approach for some types
+of interaction.
+
+### Endpoints
+
+The FCREPO root endpoint is `/rest`. The LAKEsuperior root endpoint is `/ldp`.
+
+This should not pose a problem if a client does not have `rest` hard-coded in
+its code, but in any event, the `/rest` endpoint is provided for backwards
+compatibility.
+
+LAKEsuperior adds the (currently stub) `query` endpoint. Other endpoints for
+non-LDP services may be opened in the future.
+
+### Automatic LDP class assignment
+
+Since LAKEsuperior rejects client-provided server-managed triples, and since
+the LDP types are among them, the LDP container type is inferred from the
+provided properties: if the `ldp:hasMemberRelation` and
+`ldp:membershipResource` properties are provided, the resource is a Direct
+Container. If in addition to these the `ldp:insertedContentRelation` property
+is present, the resource is an Indirect Container. If any of the first two are
+missing, the resource is a Container (@TODO discuss: shall it be a Basic
+Container?)
+
+Clients are encouraged to omit LDP types in PUT, POST and PATCH requests.
+
+### Lenient handling
 
 FCREPO4 requires server-managed triples to be expressly indicated in a PUT
 request, unless the `Prefer` heeader is set to
@@ -55,7 +130,16 @@ the default.
 If `Prefer` is set to `handling=lenient`, all server-managed triples sent with
 the payload are ignored.
 
-## "Include" and "Omit" options for children
+Clients using the `Prefer` header to control PUT behavior as advertised by the
+specs should not notice any difference.
+
+
+## Optional improvements
+
+The following are improvements in performance or usability that can only taken
+advantage of if client code is adjusted.
+
+### "Include" and "Omit" options for children
 
 LAKEsuperior offers an additional `Prefer` header option to exclude all
 references to child resources (i.e. by removing all the `ldp:contains` triples)
@@ -65,18 +149,7 @@ while leaving the other server-managed triples when retrieving a resource:
 
 The default behavior is including all children URIs.
 
-## Automatic LDP class assignment
-
-Since LAKEsuperior rejects client-provided server-managed triples, and since
-the LDP types are among them, the LDP container type is inferred from the
-provided properties: if the `ldp:hasMemberRelation` and
-`ldp:membershipResource` properties are provided, the resource is a Direct
-Container. If in addition to these the `ldp:insertedContentRelation` property
-is present, the resource is an Indirect Container. If any of the first two are
-missing, the resource is a Container (@TODO discuss: shall it be a Basic
-Container?)
-
-## LDP-NR metadata by content negotiation
+### LDP-NR metadata by content negotiation
 
 FCREPO4 relies on the `/fcr:metadata` identifier to retrieve RDF metadata about
 an LDP-NR. LAKEsuperior supports this as a legacy option, but encourages the
@@ -84,37 +157,7 @@ use of content negotiation to do the same. Any request to an LDP-NR with an
 `Accept` header set to one of the supported RDF serialization formats will
 yield the RDF metadata of the resource instead of the binary contents.
 
-## Tombstone methods
-
-If a client requests a tombstone resource in
-FCREPO4 with a method other than DELETE, the server will return `405 Method Not
-Allowed` regardless of whether the tombstone exists or not.
-
-LAKEsuperior will return `405` only if the tombstone actually exists, `404`
-otherwise.
-
-## Optional deletion without leaving tombstone
+### Optional deletion without leaving tombstone
 
 In LAKEsuperior, setting the `Prefer:no-tombstone` header option allows to
 delete a resource without leaving a tombstone.
-
-## Atomicity
-
-FCREPO4 supports batch atomic operations whereas a transaction can be opened
-and a number of operations (i.e. multiple R/W requests to the repository) can
-be performed. The operations are persisted in the repository only if and when
-the transaction is committed.
-
-LAKesuperior only supports atomicity for a single LDP request. I.e. a single
-HTTTP request that should reult in multiple write operations to the storage
-layer is only persisted if no exception is thrown. Otherwise, the operation is
-rolled back in order to prevent resources to be left in an inconsistent state.
-
-## Web UI
-
-FCREPO4 includes a web UI for simple CRUD operations.
-
-Such a UI is not foreseen to be built in LAKEsuperior any time soon since the
-API interaction leaves a greater degree of flexibility. In addition, the
-underlying triplestore layer may provide a UI for complex RDF queries.
-