firestore: breaking behavior changes

[Jonathan Amsterdam]

We just committed the following changes. You'll see them if you run "go get -u", but if you're using dep or another tool to pin to a release version, they won't appear until v0.21.0 is tagged, sometime next month.

These changes do not break the package surface—your code will still compile—but they do affect how you write code.

The first affects how we return information about non-existent documents. DocumentRef.Get and Transaction.Get still return a NotFound error if the document does not exist, but in addition their first return value, instead of being nil, is a DocumentSnapshot whose Exists method returns false. This DocumentSnapshot has a non-zero ReadTime, which some may find useful. This change is unlikely to affect working programs, since they should have ignored the first return value if the error was non-nil.

Similarly, instead of the DocumentRef.GetAll and Transaction.GetAll methods returning nil for a non-existent document, they will return a DocumentSnapshot whose Exists method returns false, with a valid ReadTime. This change will break code that compares with nil to detect missing documents.

The second change adds a Stop method to DocumentIterator. Whenever you call the Documents method on a Query or CollectionRef, you should call Stop on the returned iterator, typically by using defer:

iter := q.Documents(ctx)

defer iter.Stop()

You don't need to call Stop if you always iterate until the end (that is, until DocumentIterator.Next returns iterator.Done). That includes calling GetAll, so the following code is fine:

q.Documents(ctx).GetAll()

However, if you break the iteration in the middle and don't call Stop, your program will leak resources. To be clear, all existing programs that do this already leak; we're adding the Stop method to provide a way to fix that bug.