google-cloud-firestore 2.6.0 → 2.6.6

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3141b004673c1db562f162d9218ac680c0693e4d91a8eb48b7d17f444646e74a
4
- data.tar.gz: 4ab2bb6f69da5f8ad2e53464ae3712647b3642d49a465dc5f75d1dbc923979f5
3
+ metadata.gz: 644103521f4d29009f610f18e1809da1c919f4cd8f6f5d592ac5aa9748f1df65
4
+ data.tar.gz: 8205ef1bfed0ce2eb11e3bc0ffebf06225d78c8d6c4cc9806faf3dc8cf6dc58e
5
5
  SHA512:
6
- metadata.gz: fd5dccbe067d6fea81556aae40b9fc9de2ca75fc389c919335217371d84578b68ad7c9854c84831bb368dd58982849c06f044cef0c864be586cdace0ea48994a
7
- data.tar.gz: 7a7f0ee2a3259f2a65119b0b31dbf781d7336f7c530301f4c7f0a7fdf95fea8a7773caa4ed172c9ce8c5ff9f9fe80dab830f37ef1e6d204ae7d770fdf9c066c0
6
+ metadata.gz: cb058bd5c47ffac3c46f0294d2f965f7994457bedf0c6b343f9bc42864516c32d037e7f0f6dc71b319cb9bc973d4af364eda9a7ff5a83e36b56e7a2db31c566f
7
+ data.tar.gz: a30c9c15c43df87049dbbc07c76e37892b90aa053a407a96b410947a6b8e720e293f558a95d0d5518d578c4a1bc1054f2525498fa1cdf02465b6ef9f11750a0f
data/AUTHENTICATION.md CHANGED
@@ -95,7 +95,8 @@ client = Google::Cloud::Firestore.new
95
95
 
96
96
  ### Configuration
97
97
 
98
- The **Project ID** and **Credentials JSON** can be configured instead of placing them in environment variables or providing them as arguments.
98
+ The **Project ID** and the path to the **Credentials JSON** file can be configured
99
+ instead of placing them in environment variables or providing them as arguments.
99
100
 
100
101
  ```ruby
101
102
  require "google/cloud/firestore"
data/CHANGELOG.md CHANGED
@@ -1,5 +1,42 @@
1
1
  # Release History
2
2
 
3
+ ### 2.6.6 / 2022-01-11
4
+
5
+ #### Documentation
6
+
7
+ * Fix samples/CONTRIBUTING.md
8
+ * Update version managers list in CONTRIBUTING.md
9
+
10
+ ### 2.6.5 / 2021-10-25
11
+
12
+ #### Documentation
13
+
14
+ * Add documentation for quota_project Configuration attribute
15
+
16
+ ### 2.6.4 / 2021-08-26
17
+
18
+ #### Bug Fixes
19
+
20
+ * Fix google-cloud-resource-prefix header
21
+
22
+ ### 2.6.3 / 2021-08-24
23
+
24
+ #### Bug Fixes
25
+
26
+ * Fix transaction retry behavior
27
+
28
+ ### 2.6.2 / 2021-07-26
29
+
30
+ #### Bug Fixes
31
+
32
+ * Update FieldPath#formatted_string to correctly escape non-simple characters
33
+
34
+ ### 2.6.1 / 2021-07-08
35
+
36
+ #### Documentation
37
+
38
+ * Update AUTHENTICATION.md in handwritten packages
39
+
3
40
  ### 2.6.0 / 2021-06-15
4
41
 
5
42
  #### Features
data/CONTRIBUTING.md CHANGED
@@ -1,187 +1,418 @@
1
1
  # Contributing to Google Cloud Firestore
2
2
 
3
- 1. **Sign one of the contributor license agreements below.**
4
- 2. Fork the repo, develop and test your code changes.
5
- 3. Send a pull request.
3
+ Thank you for your interest in making a contribution to google-cloud-ruby. Community contributions are an essential part
4
+ of open source, and we want to make contributing easy for you. If you have any suggestions for how to improve this
5
+ guide, please [open an issue](https://github.com/googleapis/google-cloud-ruby/issues) and let us know!
6
6
 
7
- ## Contributor License Agreements
7
+ ### Code of Conduct
8
8
 
9
- Before we can accept your pull requests you'll need to sign a Contributor
10
- License Agreement (CLA):
9
+ Please note that this project is covered by a Contributor Code of Conduct. By participating in this project you agree to
10
+ abide by its terms. See {file:CODE_OF_CONDUCT.md Code of Conduct} for more information.
11
11
 
12
- - **If you are an individual writing original source code** and **you own the
13
- intellectual property**, then you'll need to sign an [individual
14
- CLA](https://developers.google.com/open-source/cla/individual).
15
- - **If you work for a company that wants to allow you to contribute your work**,
16
- then you'll need to sign a [corporate
12
+ ## Overview
13
+
14
+ 1. [Open an issue](#open-an-issue)
15
+ 1. [Sign Contributor License Agreement](#sign-contributor-license-agreement)
16
+ 1. [Set up environment](#set-up-environment)
17
+ 1. [Run CI](#run-ci)
18
+ 1. [Make changes](#make-changes)
19
+ 1. [Commit changes](#commit-changes)
20
+ 1. [Run CI again](#run-ci-again)
21
+ 1. [Submit your pull request](#submit-your-pull-request)
22
+
23
+ ## Open an issue
24
+
25
+ Pull requests should generally be directed by an existing issue, otherwise you risk working on something that the
26
+ maintainers might not be able to accept into the project. Please take a look through [the repository
27
+ issues](https://github.com/googleapis/google-cloud-ruby/issues?q=is%3Aissue+label%3A%22api%3A+firestore%22), and if you
28
+ do not see an existing issue for your problem or feature, please open one using one of the provided templates.
29
+
30
+ ## Sign Contributor License Agreement
31
+
32
+ Before we can accept your pull requests you'll need to sign a Contributor License Agreement (CLA):
33
+
34
+ - **If you are an individual writing original source code** and **you own the intellectual property**, then you'll need
35
+ to sign an [individual CLA](https://developers.google.com/open-source/cla/individual).
36
+ - **If you work for a company that wants to allow you to contribute your work**, then you'll need to sign a [corporate
17
37
  CLA](https://developers.google.com/open-source/cla/corporate).
18
38
 
19
- You can sign these electronically (just scroll to the bottom). After that, we'll
20
- be able to accept your pull requests.
39
+ You can sign these electronically. After that, we'll be able to accept your pull requests.
40
+
41
+ ## Set up environment
42
+
43
+ Before you start on a pull request, you should prepare your work environment for development, acceptance testing and the
44
+ interactive console (optional).
21
45
 
22
- ## Setup
46
+ ### Local development setup
23
47
 
24
- In order to use the google-cloud-firestore console and run the project's tests,
25
- there is a small amount of setup:
48
+ To set up your local development environment:
26
49
 
27
- 1. Install Ruby. google-cloud-firestore requires Ruby 2.5+. You may choose to
28
- manage your Ruby and gem installations with [RVM](https://rvm.io/),
29
- [rbenv](https://github.com/rbenv/rbenv), or
30
- [chruby](https://github.com/postmodern/chruby).
50
+ 1. Install a [supported version](google-cloud-firestore.gemspec) (or versions) of Ruby. (You may choose to manage your
51
+ Ruby and gem installations with [RVM](https://rvm.io/), [rbenv](https://github.com/rbenv/rbenv),
52
+ [chruby](https://github.com/postmodern/chruby) or a similar tool.)
31
53
 
32
- 2. Install [Bundler](http://bundler.io/).
54
+ 1. Install [Bundler](http://bundler.io/).
33
55
 
34
56
  ```sh
35
57
  $ gem install bundler
36
58
  ```
37
59
 
38
- 3. Install the top-level project dependencies.
60
+ 1. [Fork](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks) the
61
+ [google-cloud-ruby](https://github.com/googleapis/google-cloud-ruby) repo, clone your fork, and configure the
62
+ `upstream`
63
+ [remote](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/configuring-a-remote-for-a-fork):
64
+
65
+ ```bash
66
+ git clone https://github.com/<your-username>/google-cloud-ruby.git
67
+ cd google-cloud-ruby
68
+ git remote add upstream git@github.com:googleapis/google-cloud-ruby.git
69
+ ```
70
+
71
+ 1. If your fork and clone are not brand new, get the latest changes from `upstream`:
72
+
73
+ ```bash
74
+ git checkout main
75
+ git pull upstream main
76
+ ```
77
+
78
+ 1. Change to the library's sub-directory in the repo:
39
79
 
40
80
  ```sh
41
- $ bundle install
81
+ $ cd google-cloud-firestore
42
82
  ```
43
83
 
44
- 4. Install the Firestore dependencies.
84
+ 1. Install (or update) the library dependencies:
45
85
 
46
86
  ```sh
47
- $ cd google-cloud-firestore/
48
- $ bundle install
87
+ $ bundle update
88
+ ```
89
+
90
+ 1. Create a new topic branch off of the `main` branch:
91
+
92
+ ```bash
93
+ git checkout -b <topic-branch>
49
94
  ```
50
95
 
51
- ## Console
96
+ ### Acceptance tests setup
52
97
 
53
- In order to run code interactively, you can automatically load
54
- google-cloud-firestore and its dependencies in IRB. This requires that your
55
- developer environment has already been configured by following the steps
56
- described in the {file:AUTHENTICATION.md Authentication Guide}. An IRB console
57
- can be created with:
98
+ To set up your acceptance test credentials:
58
99
 
59
- ```sh
60
- $ cd google-cloud-firestore/
61
- $ bundle exec rake console
62
- ```
100
+ 1. If needed, create a Google Cloud project. In the Google Cloud Console, on the project selector page, select or create
101
+ a project.
102
+
103
+ 1. Ensure that billing is enabled for your project.
104
+
105
+ 1. Ensure that the Firestore API is enabled for your project. Note that if you have already enabled the Datastore API
106
+ for your project, you will need to use a different project for Firestore.
107
+
108
+ 1. Follow the instructions for [Creating a Service Account](AUTHENTICATION.md#creating-a-service-account) in
109
+ `AUTHENTICATION.md`, including downloading and securely storing a JSON key file.
63
110
 
64
- ## Firestore Tests
111
+ 1. Set the `GCLOUD_TEST_KEYFILE` environment variable to the path of the JSON key file that you downloaded in the
112
+ previous step:
65
113
 
66
- Tests are very important part of google-cloud-firestore. All contributions
67
- should include tests that ensure the contributed code behaves as expected.
114
+ ``` sh
115
+ $ export GCLOUD_TEST_KEYFILE=/path/to/keyfile.json
116
+ ```
117
+
118
+ If you are already using the `GCLOUD_TEST_KEYFILE` environment variable, and wish to test this library with a
119
+ different key file, you may set the `FIRESTORE_TEST_KEYFILE` environment variable instead:
120
+
121
+ ``` sh
122
+ $ export FIRESTORE_TEST_KEYFILE=/path/to/keyfile.json
123
+ ```
124
+
125
+ 1. Set the `GCLOUD_TEST_PROJECT` environment variable to your Google Cloud project ID:
126
+
127
+ ``` sh
128
+ $ export GCLOUD_TEST_PROJECT=my-project-id
129
+ ```
68
130
 
69
- To run the unit tests, documentation tests, and code style checks together for a
70
- package:
131
+ If you are already using the `GCLOUD_TEST_PROJECT` environment variable, and wish to test this library with a
132
+ different project, you may set the `FIRESTORE_TEST_PROJECT` environment variable instead:
133
+
134
+ ``` sh
135
+ $ export FIRESTORE_TEST_PROJECT=my-project-id
136
+ ```
137
+
138
+ ### Interactive console setup (optional)
139
+
140
+ To set up your interactive console credentials:
141
+
142
+ 1. Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account JSON key file (see
143
+ above):
144
+
145
+ ``` sh
146
+ $ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/keyfile.json
147
+ ```
148
+
149
+ If you are already using the `GOOGLE_APPLICATION_CREDENTIALS` environment variable, and wish to test this library
150
+ with a different key file, you may set the `FIRESTORE_CREDENTIALS` environment variable instead:
151
+
152
+ ``` sh
153
+ $ export FIRESTORE_CREDENTIALS=/path/to/keyfile.json
154
+ ```
155
+
156
+ 1. Set the `GOOGLE_CLOUD_PROJECT` environment variable to your Google Cloud project ID:
157
+
158
+ ``` sh
159
+ $ export GOOGLE_CLOUD_PROJECT=my-project-id
160
+ ```
161
+
162
+ If you are already using the `GOOGLE_CLOUD_PROJECT` environment variable, and wish to test this library with a
163
+ different project, you may set the `FIRESTORE_PROJECT` environment variable instead:
164
+
165
+ ``` sh
166
+ $ export FIRESTORE_PROJECT=my-project-id
167
+ ```
168
+
169
+
170
+ ## Run CI
171
+
172
+ You are now ready to run local CI checks for the library, which you should do **before** you make any changes. Doing so
173
+ ensures that everything is OK with your local environment and the latest dependency versions. You don't want any
174
+ surprises later.
175
+
176
+ If you haven't already done so, change to the library's sub-directory in the repo:
177
+
178
+ ```sh
179
+ $ cd google-cloud-firestore
180
+ ```
181
+
182
+ To run the code style checks, documentation tests, and unit tests together, use the `ci` task:
71
183
 
72
184
  ``` sh
73
- $ cd google-cloud-firestore/
74
185
  $ bundle exec rake ci
75
186
  ```
76
187
 
77
- To run the command above, plus all acceptance tests, use `rake ci:acceptance` or
78
- its handy alias, `rake ci:a`.
188
+ To run the command above, plus all acceptance tests, use `rake ci:acceptance` or its handy alias, `rake ci:a`. Keep in
189
+ mind that the acceptance tests typically take longer than the other CI checks and require authentication credentials.
190
+ See the [Acceptance tests](#Acceptance-tests) section below for more information.
79
191
 
80
- ### Firestore Unit Tests
192
+ The Rake tasks aggregated in the commands above can be run individually to streamline your workflow when developing or
193
+ debugging.
81
194
 
195
+ | CI check | Command |
196
+ |-----------------------------------------------|------------------ |
197
+ | [Static code analysis](#Static-code-analysis) | `rake rubocop` |
198
+ | [Documentation tests](#Documentation-tests) | `rake doctest` |
199
+ | [Unit tests](#Unit-tests) | `rake test` |
200
+ | [Acceptance tests](#Acceptance-tests) | `rake acceptance` |
82
201
 
83
- The project uses the [minitest](https://github.com/seattlerb/minitest) library,
84
- including [specs](https://github.com/seattlerb/minitest#specs),
85
- [mocks](https://github.com/seattlerb/minitest#mocks) and
86
- [minitest-autotest](https://github.com/seattlerb/minitest-autotest).
202
+ The subsections below describe the individual CI checks.
87
203
 
88
- To run the Firestore unit tests:
204
+ ### Static code analysis
89
205
 
90
- ``` sh
91
- $ cd google-cloud-firestore/
92
- $ bundle exec rake test
206
+ The project uses [Rubocop](https://github.com/rubocop/rubocop) configured with the shared
207
+ [googleapis/ruby-style](https://github.com/googleapis/ruby-style) rules to ensure that your code adheres to
208
+ Google's Ruby style. The style is largely based on [The Ruby Style
209
+ Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions:
210
+
211
+ * Avoid parentheses when possible, including in method definitions.
212
+ * Use double-quoted strings.
213
+
214
+ You can check your code against these rules by running the Rubocop Rake task:
215
+
216
+ ```sh
217
+ $ bundle exec rake rubocop
93
218
  ```
94
219
 
95
- ### Firestore Documentation Tests
220
+ In the rare case that you need to override the existing Rubocop configuration for this library in order to accommodate
221
+ your changes, you can do so by updating [.rubocop.yml](.rubocop.yml).
96
222
 
97
- The project tests the code examples in the gem's
98
- [YARD](https://github.com/lsegal/yard)-based documentation.
223
+ ### Documentation tests
99
224
 
100
- The example testing functions in a way that is very similar to unit testing, and
101
- in fact the library providing it,
102
- [yard-doctest](https://github.com/p0deje/yard-doctest), is based on the
103
- project's unit test library, [minitest](https://github.com/seattlerb/minitest).
225
+ When adding a new feature, you should almost always add one or more in-line documentation code examples demonstrating
226
+ the use of the feature, using [YARD](https://github.com/lsegal/yard)'s
227
+ [`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag. Be sure to write a complete, executable
228
+ example that includes the library `require` statement and client initialization.
104
229
 
105
- To run the Firestore documentation tests:
230
+ The project uses [yard-doctest](https://github.com/p0deje/yard-doctest) to execute each sample as a unit test:
106
231
 
107
232
  ``` sh
108
- $ cd google-cloud-firestore/
109
233
  $ bundle exec rake doctest
110
234
  ```
111
235
 
112
- If you add, remove or modify documentation examples when working on a pull
113
- request, you may need to update the setup for the tests. The stubs and mocks
114
- required to run the tests are located in `support/doctest_helper.rb`. Please
115
- note that much of the setup is matched by the title of the
116
- [`@example`](http://www.rubydoc.info/gems/yard/file/docs/Tags.md#example) tag.
117
- If you alter an example's title, you may encounter breaking tests.
118
-
119
- ### Firestore Acceptance Tests
120
-
121
- The Firestore acceptance tests interact with the live service API. Follow the
122
- instructions in the {file:AUTHENTICATION.md Authentication Guide} for enabling
123
- the Firestore API. Occasionally, some API features may not yet be generally
124
- available, making it difficult for some contributors to successfully run the
125
- entire acceptance test suite. However, please ensure that you do successfully
126
- run acceptance tests for any code areas covered by your pull request.
236
+ If you add, remove or modify documentation examples, you may need to update the setup for the tests. The fixtures, stubs
237
+ and mocks required to run the tests are located in [support/doctest_helper.rb](support/doctest_helper.rb). Please note
238
+ that much of the setup is matched to its corresponding example by the title of the `@example` tag. If you alter an
239
+ example's title, you may encounter broken tests.
127
240
 
128
- To run the acceptance tests, first create and configure a project in the Google
129
- 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
130
- the KEYFILE location on your system.
241
+ There are generally no assertions or mock verifications in these tests. They simply check that the examples are
242
+ syntactically correct and execute against the library source code without error.
131
243
 
132
- Before you can run the Firestore acceptance tests, you must first create indexes
133
- used in the tests.
244
+ ### Unit tests
134
245
 
135
- #### Running the Firestore acceptance tests
246
+ The project uses the [minitest](https://github.com/seattlerb/minitest) library, including
247
+ [specs](https://github.com/seattlerb/minitest#specs-), [mocks](https://github.com/seattlerb/minitest#mocks-),
248
+ [minitest-autotest](https://github.com/seattlerb/minitest-autotest), and
249
+ [minitest-focus](https://github.com/seattlerb/minitest-focus).
136
250
 
137
- To run the Firestore acceptance tests:
251
+ To run the unit tests:
138
252
 
139
253
  ``` sh
140
- $ cd google-cloud-firestore/
141
- $ bundle exec rake acceptance[\\{my-project-id},\\{/path/to/keyfile.json}]
254
+ $ bundle exec rake test
142
255
  ```
143
256
 
144
- Or, if you prefer you can store the values in the `GCLOUD_TEST_PROJECT` and
145
- `GCLOUD_TEST_KEYFILE` environment variables:
257
+ Although the unit tests are intended to run quickly, during development or debugging you may want to isolate one or more
258
+ of the tests by placing the `focus` keyword just above the test declaration. (See
259
+ [minitest-focus](https://github.com/seattlerb/minitest-focus) for details.)
146
260
 
147
- ``` sh
148
- $ cd google-cloud-firestore/
149
- $ export GCLOUD_TEST_PROJECT=\\{my-project-id}
150
- $ export GCLOUD_TEST_KEYFILE=\\{/path/to/keyfile.json}
151
- $ bundle exec rake acceptance
152
- ```
261
+ #### Conformance tests
262
+
263
+ Conformance tests are a subset of the unit test suite. The generated [conformance
264
+ tests](test/google/cloud/firestore/conformance_test.rb) are based on specifications that are imported from the
265
+ `firestore` subdirectory in the [googleapis/conformance-tests](https://github.com/googleapis/conformance-tests/) repo to
266
+ the `conformance` directory. (Currently, the import process involves manually copying the files whenever they are
267
+ changed in their source repo.) You should never change conformance test specifications in this repo.
268
+
269
+ Because the conformance tests are dynamically generated at run time, working with them is more difficult than working
270
+ with hand-written tests. If you need execute one or more of these tests in isolation, you can do so by placing the
271
+ `focus` keyword just above one of the calls to `define_method`. This will isolate a subset of the conformance tests. To
272
+ isolate a single conformance test within the subset, insert a conditional statement into the `test_file.tests.each` loop
273
+ near the bottom of the `conformance_test.rb` file. In the conditional, call `next` unless the current test `description`
274
+ matches the test you want to isolate.
275
+
276
+ ### Acceptance Tests
277
+
278
+ The acceptance tests (a.k.a. integration tests) ensure that the library works correctly against the live service API.
279
+ To configure your Google Cloud project, see [Acceptance tests setup](#acceptance-tests-setup) above.
280
+
281
+ **Warning: You may incur charges while running the acceptance tests against your Google Cloud project.**
282
+
283
+ Like the unit tests, the acceptance tests are based on the [minitest](https://github.com/seattlerb/minitest) library,
284
+ including [specs](https://github.com/seattlerb/minitest#specs-) and
285
+ [minitest-focus](https://github.com/seattlerb/minitest-focus). Mocks are not generally used in acceptance tests.
286
+
287
+ Because the acceptance test suite is often time-consuming to run in its entirety, during development or debugging you
288
+ may want to isolate one or more of the tests by placing the `focus` keyword just above the test declaration. (See
289
+ [minitest-focus](https://github.com/seattlerb/minitest-focus) for details.)
153
290
 
154
- If you want to use a different project and credentials for acceptance tests, you
155
- can use the more specific `FIRESTORE_TEST_PROJECT` and `FIRESTORE_TEST_KEYFILE`
156
- environment variables:
291
+ To run the acceptance tests:
157
292
 
158
293
  ``` sh
159
- $ cd google-cloud-firestore/
160
- $ export FIRESTORE_TEST_PROJECT=\\{my-project-id}
161
- $ export FIRESTORE_TEST_KEYFILE=\\{/path/to/keyfile.json}
162
294
  $ bundle exec rake acceptance
163
295
  ```
164
296
 
165
- ## Coding Style
297
+ Some acceptance tests may depend on API features that are not yet generally available, and will fail unless your project
298
+ is added to an internal allowlist. There may also be tests that usually pass but fail occasionally due to issues like
299
+ eventual consistency. However, please ensure that you do successfully run acceptance tests for any code areas covered by
300
+ your pull request.
166
301
 
167
- Please follow the established coding style in the library. The style is is
168
- largely based on [The Ruby Style
169
- Guide](https://github.com/bbatsov/ruby-style-guide) with a few exceptions based
170
- on seattle-style:
302
+ ## Make changes
171
303
 
172
- * Avoid parenthesis when possible, including in method definitions.
173
- * Always use double quotes strings. ([Option
174
- B](https://github.com/bbatsov/ruby-style-guide#strings))
304
+ All contributions should include new or updated tests to ensure that the contributed code behaves as expected.
175
305
 
176
- You can check your code against these rules by running Rubocop like so:
306
+ When starting work on a new feature, it often makes sense to begin with a basic acceptance test to ensure that the new
307
+ feature is present in the live service API and is available to your project. To run your new test exclusively,
308
+ temporarily add the `focus` keyword just above the test declaration. (See
309
+ [minitest-focus](https://github.com/seattlerb/minitest-focus) for details.) Also, the acceptance tests have a retry
310
+ mechanism that can sometimes make it hard to see the correct error when things go wrong. To disable retries while
311
+ debugging errors, temporarily comment out or remove the `run_one_method` method definition in
312
+ [acceptance/firestore_helper.rb](acceptance/firestore_helper.rb).
313
+
314
+ When you are done developing, be sure to remove any usages of the `focus` keyword from your tests and restore the
315
+ `run_one_method` method definition if you removed it.
316
+
317
+ ### Console
318
+
319
+ The project includes a Rake task that automatically loads `google-cloud-firestore` and its dependencies in IRB. To
320
+ configure your Google Cloud project for IRB, see [Interactive console setup](#interactive-console-setup-optional) above.
321
+
322
+ **Warning: You may incur charges while using the library with your Google Cloud project.**
323
+
324
+ If you haven't already done so, change to the library's sub-directory in the repo:
177
325
 
178
326
  ```sh
179
- $ cd google-cloud-firestore/
180
- $ bundle exec rake rubocop
327
+ $ cd google-cloud-firestore
328
+ ```
329
+
330
+ The preloaded IRB console can be used as follows:
331
+
332
+ ```sh
333
+ $ bundle exec rake console
334
+ irb(main):001:0> require "google/cloud/firestore"
335
+ => true
336
+ irb(main):002:0> firestore = Google::Cloud::Firestore.new
337
+ => #<Google::Cloud::Firestore::Client:0x00007fea21c8b488 @service=Google::Cloud::Firestore::Service(my-project-id)>
338
+ irb(main):003:0>
339
+ ```
340
+
341
+ Using the console provides an interactive alternative to acceptance testing that may make it easier to explore usage and
342
+ debug problems.
343
+
344
+ ## Commit changes
345
+
346
+ Commit your changes using [conventional commits](https://www.conventionalcommits.org/), making sure to include the
347
+ associated GitHub issue number. Below is an example of a `feat` type commit that will result in a semver `minor`
348
+ release. Notice how it is scoped to the short name of the library, contains a bulleted list of public API changes, and
349
+ ends with the `closes` GitHub keyword. If this is the only new commit in your branch when you open your pull request,
350
+ the commit body including the `closes` phrase will be copied to your PR description. If you have multiple commits, you
351
+ should copy the body of this anchor commit manually to the PR description, so that GitHub will [automatically close the
352
+ related issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue).
353
+
354
+ ```bash
355
+ git commit -am "feat(firestore): Add my new feature
356
+
357
+ * Add MyClass#my_method
358
+
359
+ closes: #123"
181
360
  ```
182
361
 
183
- ## Code of Conduct
362
+ The messages for any subsequent commits you may add do not necessarily need to follow the conventional commits format,
363
+ as these messages will be manually dropped or added as bullet points to the original message when the PR is squashed and
364
+ merged.
365
+
366
+ ## Run CI again
367
+
368
+
369
+ 1. If you haven't already done so, change to the library's sub-directory in the repo:
370
+
371
+ ```sh
372
+ $ cd google-cloud-firestore
373
+ ```
374
+
375
+ 1. Rebase your topic branch on the upstream `main` branch:
376
+
377
+ ```bash
378
+ git pull --rebase upstream main
379
+ ```
380
+
381
+ 1. Run the `ci` task:
382
+
383
+ ``` sh
384
+ $ bundle exec rake ci
385
+ ```
386
+
387
+ 1. Run the `acceptance` task:
388
+
389
+ ``` sh
390
+ $ bundle exec rake acceptance
391
+ ```
392
+
393
+ Ensure that everything is passing in `rake ci` and `rake acceptance`, or at least that `rake ci` is green and you
394
+ haven't broken anything new in `rake acceptance`, before you open your pull request.
395
+
396
+ ## Submit your pull request
397
+
398
+ 1. Rebase your topic branch on the upstream `main` branch:
399
+
400
+ ```bash
401
+ git pull --rebase upstream main
402
+ ```
403
+
404
+ 1. Push your topic branch to your fork:
405
+
406
+ ```bash
407
+ git push origin -u
408
+ ```
409
+
410
+ 1. Open a [pull
411
+ request](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
412
+ using the first line of your conventional commit as the title, and with the associated GitHub issue in the
413
+ description. By convention in this project, the assignee of the pull request will be the maintainer who will merge it
414
+ once it is approved. If you are a maintainer of the project, typically you should assign the pull request to
415
+ yourself.
416
+
417
+ 1. Ensure that all of the GitHub checks are passing.
184
418
 
185
- Please note that this project is released with a Contributor Code of Conduct. By
186
- participating in this project you agree to abide by its terms. See
187
- {file:CODE_OF_CONDUCT.md Code of Conduct} for more information.
@@ -628,7 +628,24 @@ module Google
628
628
  commit_return = transaction.commit
629
629
  # Conditional return value, depending on truthy commit_response
630
630
  commit_response ? commit_return : transaction_return
631
- rescue Google::Cloud::UnavailableError => e
631
+ rescue Google::Cloud::AbortedError,
632
+ Google::Cloud::CanceledError,
633
+ Google::Cloud::UnknownError,
634
+ Google::Cloud::DeadlineExceededError,
635
+ Google::Cloud::InternalError,
636
+ Google::Cloud::UnauthenticatedError,
637
+ Google::Cloud::ResourceExhaustedError,
638
+ Google::Cloud::UnavailableError,
639
+ Google::Cloud::InvalidArgumentError => e
640
+
641
+ if e.instance_of? Google::Cloud::InvalidArgumentError
642
+ # Return if a previous call was retried but ultimately succeeded
643
+ return nil if backoff[:current].positive?
644
+ # The Firestore backend uses "INVALID_ARGUMENT" for transaction IDs that have expired.
645
+ # While INVALID_ARGUMENT is generally not retryable, we retry this specific case.
646
+ raise e unless e.message =~ /transaction has expired/
647
+ end
648
+
632
649
  # Re-raise if retried more than the max
633
650
  raise e if backoff[:current] > backoff[:max]
634
651
 
@@ -643,12 +660,6 @@ module Google
643
660
  transaction = Transaction.from_client \
644
661
  self, previous_transaction: transaction.transaction_id
645
662
  retry
646
- rescue Google::Cloud::InvalidArgumentError => e
647
- # Return if a previous call was retried but ultimately succeeded
648
- return nil if backoff[:current].positive?
649
-
650
- # Re-raise error.
651
- raise e
652
663
  rescue StandardError => e
653
664
  # Rollback transaction when handling unexpected error
654
665
  transaction.rollback rescue nil
@@ -209,19 +209,15 @@ module Google
209
209
 
210
210
  protected
211
211
 
212
- START_FIELD_PATH_CHARS = /\A[a-zA-Z_]/.freeze
213
212
  INVALID_FIELD_PATH_CHARS = %r{[~*/\[\]]}.freeze
213
+ SIMPLE_FIELD_PATH_CHARS = /\A[_a-zA-Z][_a-zA-Z0-9]*\Z/.freeze
214
214
 
215
215
  def escape_field_for_path field
216
216
  field = String field
217
217
 
218
- if INVALID_FIELD_PATH_CHARS.match(field) ||
219
- field["."] || field["`"] || field["\\"]
220
- escaped_field = field.gsub(/[`\\]/, "`" => "\\\`", "\\" => "\\\\")
221
- return "`#{escaped_field}`"
222
- end
218
+ return field if SIMPLE_FIELD_PATH_CHARS.match field
223
219
 
224
- return field if START_FIELD_PATH_CHARS.match field
220
+ field = field.gsub(/[`\\]/, "`" => "\\`", "\\" => "\\\\")
225
221
 
226
222
  "`#{field}`"
227
223
  end
@@ -48,7 +48,7 @@ module Google
48
48
  config.endpoint = host if host
49
49
  config.lib_name = "gccl"
50
50
  config.lib_version = Google::Cloud::Firestore::VERSION
51
- config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}" }
51
+ config.metadata = { "google-cloud-resource-prefix": "projects/#{@project}/databases/(default)" }
52
52
  end
53
53
  end
54
54
 
@@ -16,7 +16,7 @@
16
16
  module Google
17
17
  module Cloud
18
18
  module Firestore
19
- VERSION = "2.6.0".freeze
19
+ VERSION = "2.6.6".freeze
20
20
  end
21
21
  end
22
22
  end
@@ -122,6 +122,8 @@ module Google
122
122
  # parameter `keyfile` is considered deprecated, but may also be used.)
123
123
  # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
124
124
  # the set of resources and operations that the connection can access.
125
+ # * `quota_project` - (String) The project ID for a project that can be
126
+ # used by client libraries for quota and billing purposes.
125
127
  # * `timeout` - (Integer) Default timeout to use in requests.
126
128
  # * `endpoint` - (String) Override of the endpoint host name, or `nil`
127
129
  # to use the default endpoint.
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: google-cloud-firestore
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.6.0
4
+ version: 2.6.6
5
5
  platform: ruby
6
6
  authors:
7
7
  - Google Inc
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2021-06-15 00:00:00.000000000 Z
11
+ date: 2022-01-11 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: google-cloud-core
@@ -272,7 +272,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
272
272
  - !ruby/object:Gem::Version
273
273
  version: '0'
274
274
  requirements: []
275
- rubygems_version: 3.2.17
275
+ rubygems_version: 3.3.4
276
276
  signing_key:
277
277
  specification_version: 4
278
278
  summary: API Client library for Google Cloud Firestore API