google-cloud-firestore 2.6.0 → 2.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3141b004673c1db562f162d9218ac680c0693e4d91a8eb48b7d17f444646e74a
-  data.tar.gz: 4ab2bb6f69da5f8ad2e53464ae3712647b3642d49a465dc5f75d1dbc923979f5
+  metadata.gz: 82ce640d6adf49f0b7f73b71c446fb23db7bacd6d9cd8347598b7a4a0c5bc76f
+  data.tar.gz: c81d472495db054a19b0baf395341207087f6de9466e7378ce82f113abbe87c5
 SHA512:
-  metadata.gz: fd5dccbe067d6fea81556aae40b9fc9de2ca75fc389c919335217371d84578b68ad7c9854c84831bb368dd58982849c06f044cef0c864be586cdace0ea48994a
-  data.tar.gz: 7a7f0ee2a3259f2a65119b0b31dbf781d7336f7c530301f4c7f0a7fdf95fea8a7773caa4ed172c9ce8c5ff9f9fe80dab830f37ef1e6d204ae7d770fdf9c066c0
+  metadata.gz: a9955e948ab4d0d6a2dbdd4aa214b1babb3a40f9f3b040fe08a97e91aa8ff7c756282698ea385affc5e8f82e25185ed2fb7d269b192062b0181ed0c3dd984c7f
+  data.tar.gz: 2397f244f4d9a8360d1037538d04aedfa8cea6861f5d64c41672f6ae1201ed530e1d82cb14d1bd03f430c929f00794b6058e490694c3caa314b2697fdd331dd8

data/AUTHENTICATION.md

@@ -95,7 +95,8 @@ client = Google::Cloud::Firestore.new
 
 ### Configuration
 
-The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
+The **Project ID** and the path to the **Credentials JSON** file can be configured
+instead of placing them in environment variables or providing them as arguments.
 
 ```ruby
 require "google/cloud/firestore"

data/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Release History
 
+### 2.7.0 (2022-07-02)
+
+#### Features
+
+* Updated minimum Ruby version to 2.6 ([#18446](https://github.com/googleapis/google-cloud-ruby/issues/18446)) 
+
+### 2.6.6 / 2022-01-11
+
+#### Documentation
+
+* Fix samples/CONTRIBUTING.md
+* Update version managers list in CONTRIBUTING.md
+
+### 2.6.5 / 2021-10-25
+
+#### Documentation
+
+* Add documentation for quota_project Configuration attribute
+
+### 2.6.4 / 2021-08-26
+
+#### Bug Fixes
+
+* Fix google-cloud-resource-prefix header
+
+### 2.6.3 / 2021-08-24
+
+#### Bug Fixes
+
+* Fix transaction retry behavior
+
+### 2.6.2 / 2021-07-26
+
+#### Bug Fixes
+
+* Update FieldPath#formatted_string to correctly escape non-simple characters
+
+### 2.6.1 / 2021-07-08
+
+#### Documentation
+
+* Update AUTHENTICATION.md in handwritten packages
+
 ### 2.6.0 / 2021-06-15
 
 #### Features

data/CONTRIBUTING.md

@@ -1,187 +1,418 @@
 # Contributing to Google Cloud Firestore
 
-1. **Sign one of the contributor license agreements below.**
-2. Fork the repo, develop and test your code changes.
-3. Send a pull request.
+Thank you for your interest in making a contribution to google-cloud-ruby. Community contributions are an essential part
+of open source, and we want to make contributing easy for you. If you have any suggestions for how to improve this
+guide, please [open an issue](https://github.com/googleapis/google-cloud-ruby/issues) and let us know!
 
-## Contributor License Agreements
+### Code of Conduct
 
-Before we can accept your pull requests you'll need to sign a Contributor
-License Agreement (CLA):
+Please note that this project is covered by a Contributor Code of Conduct. By participating in this project you agree to
+abide by its terms. See {file:CODE_OF_CONDUCT.md Code of Conduct} for more information.
 
-- **If you are an individual writing original source code** and **you own the
-  intellectual property**, then you'll need to sign an [individual
-  CLA](https://developers.google.com/open-source/cla/individual).
-- **If you work for a company that wants to allow you to contribute your work**,
-  then you'll need to sign a [corporate
+## Overview
+
+1. [Open an issue](#open-an-issue)
+1. [Sign Contributor License Agreement](#sign-contributor-license-agreement)
+1. [Set up environment](#set-up-environment)
+1. [Run CI](#run-ci)
+1. [Make changes](#make-changes)
+1. [Commit changes](#commit-changes)
+1. [Run CI again](#run-ci-again)
+1. [Submit your pull request](#submit-your-pull-request)
+
+## Open an issue
+
+Pull requests should generally be directed by an existing issue, otherwise you risk working on something that the
+maintainers might not be able to accept into the project. Please take a look through [the repository
+issues](https://github.com/googleapis/google-cloud-ruby/issues?q=is%3Aissue+label%3A%22api%3A+firestore%22), and if you
+do not see an existing issue for your problem or feature, please open one using one of the provided templates.
+
+## Sign Contributor License Agreement
+
+Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA):
+
+- **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need
+  to sign an [individual CLA](https://developers.google.com/open-source/cla/individual).
+- **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a [corporate
   CLA](https://developers.google.com/open-source/cla/corporate).
 
-You can sign these electronically (just scroll to the bottom). After that, we'll
-be able to accept your pull requests.
+You can sign these electronically. After that, we'll be able to accept your pull requests.
+
+## Set up environment
+
+Before you start on a pull request, you should prepare your work environment for development, acceptance testing and the
+interactive console (optional).
 
-## Setup
+### Local development setup
 
-In order to use the google-cloud-firestore console and run the project's tests,
-there is a small amount of setup:
+To set up your local development environment:
 
-1. Install Ruby. google-cloud-firestore requires Ruby 2.5+. You may choose to
-   manage your Ruby and gem installations with [RVM](https://rvm.io/),
-   [rbenv](https://github.com/rbenv/rbenv), or
-   [chruby](https://github.com/postmodern/chruby).
+1. Install a [supported version](google-cloud-firestore.gemspec) (or versions) of Ruby. (You may choose to manage your
+   Ruby and gem installations with [RVM](https://rvm.io/), [rbenv](https://github.com/rbenv/rbenv),
+   [chruby](https://github.com/postmodern/chruby) or a similar tool.)
 
-2. Install [Bundler](http://bundler.io/).
+1. Install [Bundler](http://bundler.io/).
 
    ```sh
    $ gem install bundler
    ```
 
-3. Install the top-level project dependencies.
+1. [Fork](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks) the
+   [google-cloud-ruby](https://github.com/googleapis/google-cloud-ruby) repo, clone your fork, and configure the
+   `upstream`
+   [remote](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork):
+
+   ```bash
+   git clone https://github.com/<your-username>/google-cloud-ruby.git
+   cd google-cloud-ruby
+   git remote add upstream git@github.com:googleapis/google-cloud-ruby.git
+   ```
+
+1. If your fork and clone are not brand new, get the latest changes from `upstream`:
+
+   ```bash
+   git checkout main
+   git pull upstream main
+   ```
+
+1. Change to the library's sub-directory in the repo:
 
    ```sh
-   $ bundle install
+   $ cd google-cloud-firestore
    ```
 
-4. Install the Firestore dependencies.
+1. Install (or update) the library dependencies:
 
    ```sh
-   $ cd google-cloud-firestore/
-   $ bundle install
+   $ bundle update
+   ```
+
+1. Create a new topic branch off of the `main` branch:
+
+   ```bash
+   git checkout -b <topic-branch>
    ```
 
-## Console
+### Acceptance tests setup
 
-In order to run code interactively, you can automatically load
-google-cloud-firestore and its dependencies in IRB. This requires that your
-developer environment has already been configured by following the steps
-described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
-can be created with:
+To set up your acceptance test credentials:
 
-```sh
-$ cd google-cloud-firestore/
-$ bundle exec rake console
-```
+1. If needed, create a Google Cloud project. In the Google Cloud Console, on the project selector page, select or create
+   a project.
+
+1. Ensure that billing is enabled for your project.
+
+1. Ensure that the Firestore API is enabled for your project. Note that if you have already enabled the Datastore API
+   for your project, you will need to use a different project for Firestore.
+
+1. Follow the instructions for [Creating a Service Account](AUTHENTICATION.md#creating-a-service-account) in
+   `AUTHENTICATION.md`, including downloading and securely storing a JSON key file. 
 
-## Firestore Tests
+1. Set the `GCLOUD_TEST_KEYFILE` environment variable to the path of the JSON key file that you downloaded in the
+   previous step:
 
-Tests are very important part of google-cloud-firestore. All contributions
-should include tests that ensure the contributed code behaves as expected.
+   ``` sh
+   $ export GCLOUD_TEST_KEYFILE=/path/to/keyfile.json
+   ```
+
+   If you are already using the `GCLOUD_TEST_KEYFILE` environment variable, and wish to test this library with a
+   different key file, you may set the `FIRESTORE_TEST_KEYFILE` environment variable instead:
+
+   ``` sh
+   $ export FIRESTORE_TEST_KEYFILE=/path/to/keyfile.json
+   ```
+
+1. Set the `GCLOUD_TEST_PROJECT` environment variable to your Google Cloud project ID:
+
+   ``` sh
+   $ export GCLOUD_TEST_PROJECT=my-project-id
+   ```
 
-To run the unit tests, documentation tests, and code style checks together for a
-package:
+   If you are already using the `GCLOUD_TEST_PROJECT` environment variable, and wish to test this library with a
+   different project, you may set the `FIRESTORE_TEST_PROJECT` environment variable instead:
+
+   ``` sh
+   $ export FIRESTORE_TEST_PROJECT=my-project-id
+   ```
+
+### Interactive console setup (optional)
+
+To set up your interactive console credentials:
+
+1. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account JSON key file (see
+   above):
+
+   ``` sh
+   $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
+   ```
+
+   If you are already using the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, and wish to test this library
+   with a different key file, you may set the `FIRESTORE_CREDENTIALS` environment variable instead:
+
+   ``` sh
+   $ export FIRESTORE_CREDENTIALS=/path/to/keyfile.json
+   ```
+
+1. Set the `GOOGLE_CLOUD_PROJECT` environment variable to your Google Cloud project ID:
+
+   ``` sh
+   $ export GOOGLE_CLOUD_PROJECT=my-project-id
+   ```
+
+   If you are already using the `GOOGLE_CLOUD_PROJECT` environment variable, and wish to test this library with a
+   different project, you may set the `FIRESTORE_PROJECT` environment variable instead:
+
+   ``` sh
+   $ export FIRESTORE_PROJECT=my-project-id
+   ```
+
+
+## Run CI
+
+You are now ready to run local CI checks for the library, which you should do **before** you make any changes. Doing so
+ensures that everything is OK with your local environment and the latest dependency versions. You don't want any
+surprises later.
+
+If you haven't already done so, change to the library's sub-directory in the repo:
+
+```sh
+$ cd google-cloud-firestore
+```
+
+To run the code style checks, documentation tests, and unit tests together, use the `ci` task:
 
 ``` sh
-$ cd google-cloud-firestore/
 $ bundle exec rake ci
 ```
 
-To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
-its handy alias, `rake ci:a`.
+To run the command above, plus all acceptance tests, use `rake ci:acceptance` or its handy alias, `rake ci:a`. Keep in
+mind that the acceptance tests typically take longer than the other CI checks and require authentication credentials.
+See the [Acceptance tests](#Acceptance-tests) section below for more information.
 
-### Firestore Unit Tests
+The Rake tasks aggregated in the commands above can be run individually to streamline your workflow when developing or
+debugging.
 
+| CI check                                      | Command           |
+|-----------------------------------------------|------------------ |
+| [Static code analysis](#Static-code-analysis) | `rake rubocop`    |
+| [Documentation tests](#Documentation-tests)   | `rake doctest`    |
+| [Unit tests](#Unit-tests)                     | `rake test`       |
+| [Acceptance tests](#Acceptance-tests)         | `rake acceptance` |
 
-The project uses the [minitest](https://github.com/seattlerb/minitest) library,
-including [specs](https://github.com/seattlerb/minitest#specs),
-[mocks](https://github.com/seattlerb/minitest#mocks) and
-[minitest-autotest](https://github.com/seattlerb/minitest-autotest).
+The subsections below describe the individual CI checks.
 
-To run the Firestore unit tests:
+### Static code analysis
 
-``` sh
-$ cd google-cloud-firestore/
-$ bundle exec rake test
+The project uses [Rubocop](https://github.com/rubocop/rubocop) configured with the shared
+[googleapis/ruby-style](https://github.com/googleapis/ruby-style) rules to ensure that your code adheres to
+Google's Ruby style. The style is largely based on [The Ruby Style
+Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions:
+
+* Avoid parentheses when possible, including in method definitions.
+* Use double-quoted strings.
+
+You can check your code against these rules by running the Rubocop Rake task:
+
+```sh
+$ bundle exec rake rubocop
 ```
 
-### Firestore Documentation Tests
+In the rare case that you need to override the existing Rubocop configuration for this library in order to accommodate
+your changes, you can do so by updating [.rubocop.yml](.rubocop.yml).
 
-The project tests the code examples in the gem's
-[YARD](https://github.com/lsegal/yard)-based documentation.
+### Documentation tests
 
-The example testing functions in a way that is very similar to unit testing, and
-in fact the library providing it,
-[yard-doctest](https://github.com/p0deje/yard-doctest), is based on the
-project's unit test library, [minitest](https://github.com/seattlerb/minitest).
+When adding a new feature, you should almost always add one or more in-line documentation code examples demonstrating
+the use of the feature, using [YARD](https://github.com/lsegal/yard)'s
+[`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag. Be sure to write a complete, executable
+example that includes the library `require` statement and client initialization.
 
-To run the Firestore documentation tests:
+The project uses [yard-doctest](https://github.com/p0deje/yard-doctest) to execute each sample as a unit test:
 
 ``` sh
-$ cd google-cloud-firestore/
 $ bundle exec rake doctest
 ```
 
-If you add, remove or modify documentation examples when working on a pull
-request, you may need to update the setup for the tests. The stubs and mocks
-required to run the tests are located in `support/doctest_helper.rb`. Please
-note that much of the setup is matched by the title of the
-[`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag.
-If you alter an example's title, you may encounter breaking tests.
-
-### Firestore Acceptance Tests
-
-The Firestore acceptance tests interact with the live service API. Follow the
-instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
-the Firestore API. Occasionally, some API features may not yet be generally
-available, making it difficult for some contributors to successfully run the
-entire acceptance test suite. However, please ensure that you do successfully
-run acceptance tests for any code areas covered by your pull request.
+If you add, remove or modify documentation examples, you may need to update the setup for the tests. The fixtures, stubs
+and mocks required to run the tests are located in [support/doctest_helper.rb](support/doctest_helper.rb). Please note
+that much of the setup is matched to its corresponding example by the title of the `@example` tag. If you alter an
+example's title, you may encounter broken tests.
 
-To run the acceptance tests, first create and configure a project in the Google
-Developers Console, as described in the {file:AUTHENTICATION.md Authentication Guide}. Be sure to download the JSON KEY file. Make note of the PROJECT_ID and
-the KEYFILE location on your system.
+There are generally no assertions or mock verifications in these tests. They simply check that the examples are
+syntactically correct and execute against the library source code without error.
 
-Before you can run the Firestore acceptance tests, you must first create indexes
-used in the tests.
+### Unit tests
 
-#### Running the Firestore acceptance tests
+The project uses the [minitest](https://github.com/seattlerb/minitest) library, including
+[specs](https://github.com/seattlerb/minitest#specs-), [mocks](https://github.com/seattlerb/minitest#mocks-),
+[minitest-autotest](https://github.com/seattlerb/minitest-autotest), and
+[minitest-focus](https://github.com/seattlerb/minitest-focus).
 
-To run the Firestore acceptance tests:
+To run the unit tests:
 
 ``` sh
-$ cd google-cloud-firestore/
-$ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
+$ bundle exec rake test
 ```
 
-Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
-`GCLOUD_TEST_KEYFILE` environment variables:
+Although the unit tests are intended to run quickly, during development or debugging you may want to isolate one or more
+of the tests by placing the `focus` keyword just above the test declaration. (See
+[minitest-focus](https://github.com/seattlerb/minitest-focus) for details.)
 
-``` sh
-$ cd google-cloud-firestore/
-$ export GCLOUD_TEST_PROJECT=\\{my-project-id}
-$ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
-$ bundle exec rake acceptance
-```
+#### Conformance tests
+
+Conformance tests are a subset of the unit test suite. The generated [conformance
+tests](test/google/cloud/firestore/conformance_test.rb) are based on specifications that are imported from the
+`firestore` subdirectory in the [googleapis/conformance-tests](https://github.com/googleapis/conformance-tests/) repo to
+the `conformance` directory. (Currently, the import process involves manually copying the files whenever they are
+changed in their source repo.) You should never change conformance test specifications in this repo.
+
+Because the conformance tests are dynamically generated at run time, working with them is more difficult than working
+with hand-written tests. If you need execute one or more of these tests in isolation, you can do so by placing the
+`focus` keyword just above one of the calls to `define_method`. This will isolate a subset of the conformance tests. To
+isolate a single conformance test within the subset, insert a conditional statement into the `test_file.tests.each` loop
+near the bottom of the `conformance_test.rb` file. In the conditional, call `next` unless the current test `description`
+matches the test you want to isolate.
+
+### Acceptance Tests
+
+The acceptance tests (a.k.a. integration tests) ensure that the library works correctly against the live service API.
+To configure your Google Cloud project, see [Acceptance tests setup](#acceptance-tests-setup) above.
+
+**Warning: You may incur charges while running the acceptance tests against your Google Cloud project.**
+
+Like the unit tests, the acceptance tests are based on the [minitest](https://github.com/seattlerb/minitest) library,
+including [specs](https://github.com/seattlerb/minitest#specs-) and
+[minitest-focus](https://github.com/seattlerb/minitest-focus). Mocks are not generally used in acceptance tests.
+
+Because the acceptance test suite is often time-consuming to run in its entirety, during development or debugging you
+may want to isolate one or more of the tests by placing the `focus` keyword just above the test declaration. (See
+[minitest-focus](https://github.com/seattlerb/minitest-focus) for details.)
 
-If you want to use a different project and credentials for acceptance tests, you
-can use the more specific `FIRESTORE_TEST_PROJECT`  and `FIRESTORE_TEST_KEYFILE`
-environment variables:
+To run the acceptance tests:
 
 ``` sh
-$ cd google-cloud-firestore/
-$ export FIRESTORE_TEST_PROJECT=\\{my-project-id}
-$ export FIRESTORE_TEST_KEYFILE=\\{/path/to/keyfile.json}
 $ bundle exec rake acceptance
 ```
 
-## Coding Style
+Some acceptance tests may depend on API features that are not yet generally available, and will fail unless your project
+is added to an internal allowlist. There may also be tests that usually pass but fail occasionally due to issues like
+eventual consistency. However, please ensure that you do successfully run acceptance tests for any code areas covered by
+your pull request.
 
-Please follow the established coding style in the library. The style is is
-largely based on [The Ruby Style
-Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions based
-on seattle-style:
+## Make changes
 
-* Avoid parenthesis when possible, including in method definitions.
-* Always use double quotes strings. ([Option
-  B](https://github.com/bbatsov/ruby-style-guide#strings))
+All contributions should include new or updated tests to ensure that the contributed code behaves as expected.
 
-You can check your code against these rules by running Rubocop like so:
+When starting work on a new feature, it often makes sense to begin with a basic acceptance test to ensure that the new
+feature is present in the live service API and is available to your project. To run your new test exclusively,
+temporarily add the `focus` keyword just above the test declaration. (See
+[minitest-focus](https://github.com/seattlerb/minitest-focus) for details.) Also, the acceptance tests have a retry
+mechanism that can sometimes make it hard to see the correct error when things go wrong. To disable retries while
+debugging errors, temporarily comment out or remove the `run_one_method` method definition in
+[acceptance/firestore_helper.rb](acceptance/firestore_helper.rb).
+
+When you are done developing, be sure to remove any usages of the `focus` keyword from your tests and restore the
+`run_one_method` method definition if you removed it.
+
+### Console
+
+The project includes a Rake task that automatically loads `google-cloud-firestore` and its dependencies in IRB. To
+configure your Google Cloud project for IRB, see [Interactive console setup](#interactive-console-setup-optional) above.
+
+**Warning: You may incur charges while using the library with your Google Cloud project.**
+
+If you haven't already done so, change to the library's sub-directory in the repo:
 
 ```sh
-$ cd google-cloud-firestore/
-$ bundle exec rake rubocop
+$ cd google-cloud-firestore
+```
+
+The preloaded IRB console can be used as follows:
+
+```sh
+$ bundle exec rake console
+irb(main):001:0> require "google/cloud/firestore"
+=> true
+irb(main):002:0> firestore = Google::Cloud::Firestore.new
+=> #<Google::Cloud::Firestore::Client:0x00007fea21c8b488 @service=Google::Cloud::Firestore::Service(my-project-id)>
+irb(main):003:0> 
+```
+
+Using the console provides an interactive alternative to acceptance testing that may make it easier to explore usage and
+debug problems.
+
+## Commit changes
+
+Commit your changes using [conventional commits](https://www.conventionalcommits.org/), making sure to include the
+associated GitHub issue number. Below is an example of a `feat` type commit that will result in a semver `minor`
+release. Notice how it is scoped to the short name of the library, contains a bulleted list of public API changes, and
+ends with the `closes` GitHub keyword. If this is the only new commit in your branch when you open your pull request,
+the commit body including the `closes` phrase will be copied to your PR description. If you have multiple commits, you
+should copy the body of this anchor commit manually to the PR description, so that GitHub will [automatically close the
+related issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
+
+```bash
+git commit -am "feat(firestore): Add my new feature
+
+* Add MyClass#my_method
+
+closes: #123"
 ```
 
-## Code of Conduct
+The messages for any subsequent commits you may add do not necessarily need to follow the conventional commits format,
+as these messages will be manually dropped or added as bullet points to the original message when the PR is squashed and
+merged.
+
+## Run CI again
+
+
+1. If you haven't already done so, change to the library's sub-directory in the repo:
+
+   ```sh
+   $ cd google-cloud-firestore
+   ```
+
+1. Rebase your topic branch on the upstream `main` branch:
+
+   ```bash
+   git pull --rebase upstream main
+   ```
+
+1. Run the `ci` task:
+
+   ``` sh
+   $ bundle exec rake ci
+   ```
+
+1. Run the `acceptance` task:
+
+   ``` sh
+   $ bundle exec rake acceptance
+   ```
+
+Ensure that everything is passing in `rake ci` and `rake acceptance`, or at least that `rake ci` is green and you
+haven't broken anything new in `rake acceptance`, before you open your pull request.
+
+## Submit your pull request
+
+1. Rebase your topic branch on the upstream `main` branch:
+
+   ```bash
+   git pull --rebase upstream main
+   ```
+
+1. Push your topic branch to your fork:
+
+   ```bash
+   git push origin -u
+   ```
+
+1. Open a [pull
+   request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
+   using the first line of your conventional commit as the title, and with the associated GitHub issue in the
+   description. By convention in this project, the assignee of the pull request will be the maintainer who will merge it
+   once it is approved. If you are a maintainer of the project, typically you should assign the pull request to
+   yourself.
+
+1. Ensure that all of the GitHub checks are passing.
 
-Please note that this project is released with a Contributor Code of Conduct. By
-participating in this project you agree to abide by its terms. See
-{file:CODE_OF_CONDUCT.md Code of Conduct} for more information.

data/lib/google/cloud/firestore/client.rb

@@ -164,8 +164,7 @@ module Google
         #
         def col_group collection_id
           if collection_id.include? "/"
-            raise ArgumentError, "Invalid collection_id: '#{collection_id}', " \
-              "must not contain '/'."
+            raise ArgumentError, "Invalid collection_id: '#{collection_id}', must not contain '/'."
           end
 
           CollectionGroup.from_collection_id service.documents_path, collection_id, self
@@ -628,7 +627,24 @@ module Google
             commit_return = transaction.commit
             # Conditional return value, depending on truthy commit_response
             commit_response ? commit_return : transaction_return
-          rescue Google::Cloud::UnavailableError => e
+          rescue Google::Cloud::AbortedError,
+                 Google::Cloud::CanceledError,
+                 Google::Cloud::UnknownError,
+                 Google::Cloud::DeadlineExceededError,
+                 Google::Cloud::InternalError,
+                 Google::Cloud::UnauthenticatedError,
+                 Google::Cloud::ResourceExhaustedError,
+                 Google::Cloud::UnavailableError,
+                 Google::Cloud::InvalidArgumentError => e
+
+            if e.instance_of? Google::Cloud::InvalidArgumentError
+              # Return if a previous call was retried but ultimately succeeded
+              return nil if backoff[:current].positive?
+              # The Firestore backend uses "INVALID_ARGUMENT" for transaction IDs that have expired.
+              # While INVALID_ARGUMENT is generally not retryable, we retry this specific case.
+              raise e unless e.message =~ /transaction has expired/
+            end
+
             # Re-raise if retried more than the max
             raise e if backoff[:current] > backoff[:max]
 
@@ -643,12 +659,6 @@ module Google
             transaction = Transaction.from_client \
               self, previous_transaction: transaction.transaction_id
             retry
-          rescue Google::Cloud::InvalidArgumentError => e
-            # Return if a previous call was retried but ultimately succeeded
-            return nil if backoff[:current].positive?
-
-            # Re-raise error.
-            raise e
           rescue StandardError => e
             # Rollback transaction when handling unexpected error
             transaction.rollback rescue nil

data/lib/google/cloud/firestore/convert.rb

@@ -50,15 +50,15 @@ module Google
           end
 
           def fields_to_hash fields, client
-            Hash[fields.map do |key, value|
+            fields.to_h do |key, value|
               [key.to_sym, value_to_raw(value, client)]
-            end]
+            end
           end
 
           def hash_to_fields hash
-            Hash[hash.map do |key, value|
+            hash.to_h do |key, value|
               [String(key), raw_to_value(value)]
-            end]
+            end
           end
 
           def value_to_raw value, client
@@ -304,7 +304,7 @@ module Google
             field_paths = new_data_pairs.map(&:first)
 
             delete_paths.map!(&:first)
-            root_field_paths_and_values = Hash[root_field_paths_and_values]
+            root_field_paths_and_values = root_field_paths_and_values.to_h
 
             data, nested_deletes = remove_field_value_from data, :delete
             raise ArgumentError, "DELETE cannot be nested" if nested_deletes.any?
@@ -425,7 +425,7 @@ module Google
             end
 
             # return new data hash and field path/values hash
-            [Hash[new_pairs.compact], Hash[paths]]
+            [new_pairs.compact.to_h, paths.to_h]
           end
 
           def identify_leaf_nodes hash

data/lib/google/cloud/firestore/field_path.rb

@@ -209,19 +209,15 @@ module Google
 
         protected
 
-        START_FIELD_PATH_CHARS = /\A[a-zA-Z_]/.freeze
         INVALID_FIELD_PATH_CHARS = %r{[~*/\[\]]}.freeze
+        SIMPLE_FIELD_PATH_CHARS = /\A[_a-zA-Z][_a-zA-Z0-9]*\Z/.freeze
 
         def escape_field_for_path field
           field = String field
 
-          if INVALID_FIELD_PATH_CHARS.match(field) ||
-             field["."] || field["`"] || field["\\"]
-            escaped_field = field.gsub(/[`\\]/, "`" => "\\\`", "\\" => "\\\\")
-            return "`#{escaped_field}`"
-          end
+          return field if SIMPLE_FIELD_PATH_CHARS.match field
 
-          return field if START_FIELD_PATH_CHARS.match field
+          field = field.gsub(/[`\\]/, "`" => "\\`", "\\" => "\\\\")
 
           "`#{field}`"
         end

data/lib/google/cloud/firestore/service.rb

@@ -48,7 +48,7 @@ module Google
               config.endpoint = host if host
               config.lib_name = "gccl"
               config.lib_version = Google::Cloud::Firestore::VERSION
-              config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
+              config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}/databases/(default)" }
             end
         end
 
@@ -189,7 +189,7 @@ module Google
         def document_mask mask
           return nil if mask.nil?
 
-          mask = Array(mask).map(&:to_s).reject(&:nil?).reject(&:empty?)
+          mask = Array(mask).map(&:to_s).reject(&:empty?)
           return nil if mask.empty?
 
           Google::Cloud::Firestore::V1::DocumentMask.new field_paths: mask

data/lib/google/cloud/firestore/version.rb

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Firestore
-      VERSION = "2.6.0".freeze
+      VERSION = "2.7.0".freeze
     end
   end
 end

data/lib/google/cloud/firestore/watch/inventory.rb

@@ -134,7 +134,7 @@ module Google
           end
 
           def order_for docs
-            Hash[docs.map { |doc| [doc.path, doc.updated_at] }]
+            docs.to_h { |doc| [doc.path, doc.updated_at] }
           end
 
           def current_order

data/lib/google/cloud/firestore.rb

@@ -122,6 +122,8 @@ module Google
       #   parameter `keyfile` is considered deprecated, but may also be used.)
       # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
       #   the set of resources and operations that the connection can access.
+      # * `quota_project` - (String) The project ID for a project that can be
+      #   used by client libraries for quota and billing purposes.
       # * `timeout` - (Integer) Default timeout to use in requests.
       # * `endpoint` - (String) Override of the endpoint host name, or `nil`
       #   to use the default endpoint.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore
 version: !ruby/object:Gem::Version
-  version: 2.6.0
+  version: 2.7.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-06-15 00:00:00.000000000 Z
+date: 2022-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core
@@ -72,28 +72,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.25.1
+        version: 1.26.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.25.1
+        version: 1.26.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.14'
+        version: '5.16'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.14'
+        version: '5.16'
 - !ruby/object:Gem::Dependency
   name: minitest-autotest
   requirement: !ruby/object:Gem::Requirement
@@ -265,14 +265,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.17
+rubygems_version: 3.3.14
 signing_key: 
 specification_version: 4
 summary: API Client library for Google Cloud Firestore API