RE: publish new Working Draft of Indexed Database API; deadline April 16

Hi Josh.

Thanks for the feedback. Moving forward, I will track changes and resolution of these suggestions in bug 9379 [1].

Appreciate the time you've spent on this.

Eliot

[1] http://www.w3.org/Bugs/Public/show_bug.cgi?id=9739




> -----Original Message-----
> From: public-webapps-request@w3.org [mailto:public-webapps-
> request@w3.org] On Behalf Of timeless
> Sent: Tuesday, April 12, 2011 12:32 AM
> To: Arthur Barstow
> Cc: public-webapps
> Subject: Re: publish new Working Draft of Indexed Database API; deadline
> April 16
> 
> On Sat, Apr 9, 2011 at 2:22 PM, Arthur Barstow <art.barstow@nokia.com>
> wrote:
> >  http://dvcs.w3.org/hg/IndexedDB/raw-file/tip/Overview.html

> 
> I expect this message to only have editorial comments. However, I'm not
> fond of April 16th, this month is tax month and I still need to file.
> 
> > Transaction
> > A transaction is used to interact with the data in a database.
> > Whenever data is read or written to the database this is done using a
> transaction.
> 
> maybe s/this/it/
> 
> > All transactions are created using a connection,
> 
> I don't like "using", perhaps "from"? -- I haven't gotten to the API yet.
> I'm also uncertain about 'a connection' vs. 'connections'
> 
> > which is the transactions connection.
> 
> s/transactions/transaction's/
> 
> > The transaction has a mode which determines which types of
> > interactions can be performed using the transaction.
> 
> s/using the transaction/upon it/ ? -- "The transaction" also started the
> sentence.
> 
> > The mode is set when the transaction is created and remains constant
> > for the
> 
> s/constant/fixed/
> 
> > lifetime of the transaction.
> 
> s/lifetime/life/
> 
> > The transaction also has a scope which determines which object stores
> > the transaction can interact with.
> 
> s/which.*with/the object stores with which the transaction may interact/.
> 
> > Finally, transactions have a active flag,
> 
> s/ a / an /
> s/Finally, t/T/ -- It isn't Finally -- Finally is used again in the next sentence.
> 
> > which determines if new requests can currently be placed against the
> transaction.
> 
> The prose here implies that this is mutable, it's also awkward (probably he
> use of 'currently').
> 
> > Finally, transactions also contain a request list of requests which have been
> placed against the transaction.
> 
> It seems that <placed> is treated as technical language, I'd expect it to be
> defined somewhere (or globally replaced by 'made').
> 
> > Transactions have a constant scope which is determined when the
> > transaction is created and remains constant for the lifetime of the
> transaction.
> 
> Each transaction has a fixed scope determined at creation time.
> 
> > Transactions offer some protection from application and system failures.
> 
> >  A transaction represents an atomic and durable set of data access and
> mutation operations.
> 
> I know that data can be uncountable or plural, but I'm unsure that 'access'
> fits with its use here -- should it be 'accesses'?
> 
> > This is encouraged using the automatically committing functionality
> described below.
> 
> s/using the automatically/by the automatic/
> 
> > Authors can still cause transactions to run for a long time, however
> > this is generally not a usage pattern which is recommended
> 
> s/usage pattern which is recommended/a recommended usage pattern/
> 
> > and can lead to bad user experience in some implementations.
> 
> possibly <a bad user experience> | <bad user experiences> ?
> 
> > A transaction is created using IDBDatabase.transaction.
> > The arguments passed determine what the scope of the transaction is
> 
> s/what//; s/is//
> 
> > and whether it's read only or not.
> 
> whether or not it is read-only.
> 
> > When a transaction is created its active flag is initially set to true.
> 
> > The implementation MUST allow requests to be placed against the
> > transaction whenever the active flag is true.
> 
> > This is the case even if the transaction has not yet been started.
> 
> > Until the transaction is started the implementation MUST NOT execute
> > these requests, but the implementation MUST still keep track of the
> > requests and their order.
> 
> s/, but/;/
> s/still//
> 
> > Requests may only be placed against the transaction
> 
> s/the/a/
> 
> > while the transaction is active.
> 
> s/the transaction/it/
> 
> > If a request is attempted to be placed against a transaction when
> 
> I find <request/attempted/placed> awkward, possibly because it lacks an
> actor...
> 
> > it is not active,
> 
> I believe <not active> is used here to be the technical state <not <active>>,
> perhaps it should be marked up. Otherwise as this is prose, I'd use <inactive>.
> 
> > the implementation MUST reject the attempt by throwing a
> TRANSACTION_INACTIVE_ERR exception.
> 
> Inactive is used in the exception type, it's a valid English word....
> 
> > Once an implementation is able to enforce the constraints defined for
> > the mode of the transaction,
> 
> transaction mode
> 
> > defined below, the implementation MUST asynchronously start the
> transaction.
> 
> > When this happens is affected by the mode in which the transaction is
> > opened, and which object stores are included in scope of the transaction.
> 
> s/which/the/
> s/are//
> s/scope of the transaction/the transaction's scope/
> 
> > Once the transaction has been started the implementation can start
> executing the requests placed against the transaction.
> > Unless otherwise defined requests MUST be executed in the order they
> > are placed against the transaction.
> 
> s/they/in which they/
> s/are/were/
> 
> I find <placed> <against> strange. <made> <against> seems to work
> Otherwise <placed> <into>
> 
> > Likewise, their result MUST be returned in the order the request was
> > placed against a specific transaction.
> 
> <result> appears to be used as a mass noun, but <request> is singular, I'm
> pretty sure this doesn't work.
> 
> > There is no guarantee about the order that results from requests in
> > different transactions are returned.
> 
> > Similarly, the isolation mode ensure that
> 
> ensures
> 
> > it doesn't matter which order requests placed against different transactions
> are executed.
> 
> order of requests placed against different transactions doesn't matter with
> respect to execution order.
> 
> I don't like "matter", do you mean 'affect'?
> 
> > At any time a transaction can be aborted,
> 
> A transaction can be aborted at any time,
> 
> > even if the transaction isn't currently active.
> 
> Again, <inactive> would be better.
> 
> > When a transaction is aborted
> 
> When <actor requests to abort a transaction>....
> 
> -- aborted is the result of the request plus the action taken by the agent
> 
> > the implementation MUST undo (roll back) any changes made to the
> > database using the transaction.
> 
> s/using/from|in/ ?
> 
> > This includes both changes to the contents of object stores as well as
> > additions and removals of object stores and indexes.
> 
> > A transaction can be aborted at any time before it is finished. Including if it
> isn't active or hasn't yet started.
> 
> This duplicates text from the beginning of the point and should be folded into
> the original statement.
> 
> > Once a transaction no longer can become active,
> 
> s/Once/When/
> s/no longer can/can no longer/
> 
> > and if the transaction hasn't been aborted,
> 
> Move this to the start of the sentence
> 
> > the implementation MUST automatically attempt to commit it.
> 
> I think <automatically> can be dropped
> 
> > This usually happens after all requests placed against the transaction
> > has been executed and their returned results handled,
> 
> s/has/have/
> 
> > but no new requests has been placed against the transaction.
> 
> s/but/and/
> s/has/have/
> 
> > When a transaction is committed implementation
> 
> s/committed/committed,/
> 
> > MUST atomically write any changes to the database made by requests
> placed against the transaction.
> 
> > That is, either all of the changes MUST be written, or if an error occurs,
> such as a disk write error, the implementation MUST NOT write any of the
> changes to the database.
> 
> I think "write ... to the database" isn't ideal here, what we want is for none
> of the changes to appear in the database when queried. It's certainly possible
> for bits to be written to a portion of the database which is rolled back, but
> that's still a "write" in a naive sense.
> 
> > If such an error occurs the implementation
> 
> s/occurs/occurs,/
> 
> > MUST abort the transaction by following the steps for aborting a
> > transaction, otherwise it MUST commit the transaction by following the
> > steps for committing a transaction.
> 
> > When a transaction is committed or aborted, it is said to be finished.
> > If a transaction can't be finished, for example due to the
> > implementation crashing or the user taking some explicit action to
> > cancel it, the implementation MUST abort the transaction.
> 
> <abort> here can't mean <take the steps for aborting a transaction> in the
> case where the implementation crashes.
> 
> > Transactions are opened in one of three modes.
> > The mode determine how concurrent access to
> 
> determines
> 
> > object stores in the transaction is isolated.
> 
> s/is/are/
> 
> I'm going to stop here, lest my user agent crash and my message fail to be
> committed. This appears to be about 1/6th through the document.
> It took me a few days to reach this document and I expect to cycle through a
> couple of other documents which have CfCs pending, plus I have taxes to do.
> Sorry for not getting to this sooner.
>

Received on Tuesday, 19 April 2011 22:42:08 UTC