docs(firestore-bigquery-export): first-time setup and accuracy fixes for the kit README - #3216
Conversation
Following the README as a first-time user left several steps to guess: - add a "Before you start" section: Blaze project with Firestore, .firebaserc, Node.js 24, latest Firebase CLI with the kits experiment - install from the `next` tag; `latest` is an empty 0.0.1 placeholder - document the guided `firebase functions:kits:install` path and what to enter for FUNCTION_DEFAULT_REGION - require firebase-functions and firebase-admin as direct dependencies; the kit's shrinkwrap nests its copies, so deploy fails without them - show one project layout that matches the firebase.json stanza, with package.json fields, a tsconfig and a predeploy build step - say the package ships no firebase.json and explain the `kit` field - note the role-confirmation and container-image prompts on deploy - explain that deploy prompts for every unset setting and saves the answers to .env.<projectId> - list what the manual enqueue snippets need (firebase-admin, ADC, GOOGLE_CLOUD_PROJECT, gcloud)
…ension Checked against extension 0.3.3 (source and a live install) and the deployed kit: - the extension's region came from the platform's Cloud Functions location setting, not a `LOCATION` param (removed in 2023) - FUNCTION_DEFAULT_REGION is read: the ext:migrate and kits:install entry files pass it to setGlobalOptions, and it places the functions when DATABASE_REGION is empty - drop the "Defaults" subsection: the extension already defaults DATASET_LOCATION to `us` and BIGQUERY_PROJECT_ID to the project - note IMPORT_COLLECTION_PATH was removed from the extension too - note that ext:migrate carries the instance's memory, timeout, ingress and instance limits into setGlobalOptions
…review Corrections, each checked against the kit, change tracker and CLI code: - create firebase.json before `firebase use --add`, which fails without it - each instance id, not the kit name, is the codebase: fix the deploy output example and the `lifecycle:run <codebase>` argument - a failed onStart publish only logs a warning; it no longer fails the execution as it did in the extension - a failed inline insert already writes the backup row, so an event whose enqueue fails is not retried but is not necessarily lost - roles/datastore.user is always granted - unset EXT_SELECTED_EVENTS publishes every event; only a blank value publishes none - settings marked "not required" fail the deploy when present but blank - complete the API surface list and correct when config is read - installer writes .env.<project-id>, not .env Clarity: - define codebase, kit and instance; add a "Check that it works" step - say which settings to set before the first deploy - give accepted values for partitioning, clustering, transform, CMEK and materialized-view settings; drop the internal "Field" column - move the enqueue snippet's prerequisites before it and export FUNCTION_REGION and GOOGLE_CLOUD_PROJECT - add the predeploy step to the multi-instance stanza - consistent placeholders, CLI naming, dashes and code fences
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request significantly updates the README documentation for the Firestore BigQuery Export kit, detailing the new installation, configuration, and deployment processes using the Firebase CLI kits experiment. The review feedback points out a few technical inaccuracies in the documentation: the firebase functions:log command is incorrectly shown with an unsupported --only flag, the codebase directory path for the guided installer is incorrectly described as having a nested source subdirectory, and a BigQuery placeholder uses an invalid hyphen instead of an underscore.
Cut the README from ~6,300 to ~1,900 words, in line with the other kits: merge setup into Install, fold package.json/tsconfig into the layout, shorten Provisioning, Failure handling, Migrating and Differences to their actionable points, and drop the quota, 429 and CLI discovery walkthroughs. All settings and corrections from the earlier commits are kept.
Drop the pre-release note about the next tag and install the package without a tag.
cabljac
left a comment
cabljac
left a comment
There was a problem hiding this comment.
Nice work on this, the first-time setup flow is much easier to follow and a lot of the corrections (datastore.user, EXT_SELECTED_EVENTS blank vs unset, backup on inline failure) look right to me.
Heads up that this was an AI-led review, which I've read through and trimmed, so please double-check each inline comment rather than taking it as fact, you may know a path it missed. The two I'd look at first are the manual enqueue recipe and the maxInstances cap from the 15.30.x installer template.
One more thing: the CHANGELOG entry for maxInstances: 500 says "the README describes the deploy failure a smaller quota produces and how to recover", but I think this PR removes that section (the functions:lifecycle:run afterFirstDeploy recovery). Since the CHANGELOG becomes the next RC's release notes, could you either keep a short version of it or update that line?
…directory Drop the firebase.json workaround and firebase use step.
…kup recovery steps
…'s service account
2 participants
Changes
@nexttag, guided installer, directfirebase-functions/firebase-admindeps)package.json,tsconfig.jsonandfirebase.jsonwith a build steponStartpublish only warnsEXT_SELECTED_EVENTS(unset publishes all),roles/datastore.user(always granted) and blank-value deploy failuresFUNCTION_DEFAULT_REGION, defaults,ext:migrateglobal options)