Repository navigation
Conversation
### Description Refines repository authoring and review conventions in `GEMINI.md`: - Clarifies utility harmonization in `Architecture & Module Design` to cover both reusing/extending existing subsystem helpers and extracting/unifying shared logic across callers. - Clarifies `Comments` guidance to avoid multi-paragraph JSDoc blocks on small helpers, inline comments that restate self-evident code, and repeating the same rationale across functions or tests. ### Scenarios Tested Validated `GEMINI.md` formatting and markdown structure. ### Sample Commands N/A
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request updates GEMINI.md to refine guidelines for coding agents, including clearer instructions on utility reuse, error handling remediation, writing high-signal comments, testing error recovery mechanisms, and keeping public repository metadata clean. The review feedback suggests minor stylistic improvements for consistency, specifically adding a comma after 'e.g.' in several places and slightly adjusting the phrasing of the error testing guideline for better readability.
| - **Survey prior art & harmonize utilities:** Before writing or adding any method that could be a common, reusable helper (e.g. retries, backoff, string parsing, path containment, domain transformations): | ||
| - **Check existing patterns first:** Search the codebase (`src/utils.ts` and relevant subsystems) to see if other code is doing a similar thing and how. | ||
| - **Reuse or unify immediately:** Either reuse how existing code does it, or if introducing a new common utility, unify it with existing custom implementations across the codebase immediately rather than creating diverging parallel implementations. | ||
| - **Survey prior art & harmonize utilities:** When implementing logic that is or could be shared across callers (e.g. retries, backoff, string parsing, path containment, domain transformations): |
Contributor
There was a problem hiding this comment.
For consistency with other parts of this document (such as lines 53 and 72), "e.g." should be followed by a comma ("e.g.,").
Suggested change
| - **Survey prior art & harmonize utilities:** When implementing logic that is or could be shared across callers (e.g. retries, backoff, string parsing, path containment, domain transformations): | |
| - **Survey prior art & harmonize utilities:** When implementing logic that is or could be shared across callers (e.g., retries, backoff, string parsing, path containment, domain transformations): |
References
- The repository style guide uses 'e.g.,' with a comma in lines 53 and 72. (link)
| - **Use the central `logger`** (`src/logger.ts`); never use `console.log()` for user-facing output. | ||
| - **Throw `FirebaseError`** (`src/error.ts`) for expected, user-facing errors. If the error is due to a violation of a precondition (e.g. something | ||
| that is null but should never be), specify a non-zero exit code (`{ exit: 1 }`). Error messages should clearly explain what failed and why; when actionable, provide concrete remediation guidance (e.g. the expected format, a `--force` flag, or a discovery command like `firebase <entity>:list`). | ||
| that is null but should never be), specify a non-zero exit code (`{ exit: 1 }`). Error messages should clearly explain what failed and why; when actionable, provide concrete remediation guidance using documented CLI flags, commands, or configuration options (e.g. the expected format, a `--force` flag, or a discovery command like `firebase <entity>:list`—never undocumented or legacy internal fields). |
Contributor
There was a problem hiding this comment.
For consistency with other parts of this document (such as lines 53 and 72), "e.g." should be followed by a comma ("e.g.,").
References
- The repository style guide uses 'e.g.,' with a comma in lines 53 and 72. (link)
| - **Test public interfaces:** Exercise public entry points and exported module functions rather than testing or stubbing private internal helpers. | ||
| - **Unit tests (`*.spec.ts`) should be co-located with their source files.** | ||
| - Test error cases and edge conditions, not just the "happy path." | ||
| - **Test error cases and recovery mechanisms:** Exercise failure paths and edge conditions, asserting both the specific error type/message and the underlying mechanism (e.g. retry attempt counts or state cleanup) rather than bare rejection. |
Contributor
There was a problem hiding this comment.
For consistency with other parts of this document (such as lines 53 and 72), "e.g." should be followed by a comma ("e.g.,"). Additionally, "rather than bare rejection" can be improved to "rather than a bare rejection" for better readability.
Suggested change
| - **Test error cases and recovery mechanisms:** Exercise failure paths and edge conditions, asserting both the specific error type/message and the underlying mechanism (e.g. retry attempt counts or state cleanup) rather than bare rejection. | |
| - **Test error cases and recovery mechanisms:** Exercise failure paths and edge conditions, asserting both the specific error type/message and the underlying mechanism (e.g., retry attempt counts or state cleanup) rather than a bare rejection. |
References
- The repository style guide uses 'e.g.,' with a comma in lines 53 and 72. (link)
joehan
reviewed
Oct 12, 2026
joehan
left a comment
joehan
left a comment
Member
There was a problem hiding this comment.
Seems good, feel free to ignore the GCA super nits
joehan
approved these changes
Oct 12, 2026
joehan
reviewed
Oct 12, 2026
| - `### Scenarios Tested` | ||
| - `### Sample Commands` | ||
| - Reference issues with "Fixes #123" in the description. | ||
| - **Keep public repository metadata clean:** Because `firebase-tools` is a public open-source repository, do not include internal issue tracker IDs (`b/...`), internal usernames, or automated agent task prefixes in commit messages, PR titles, or PR descriptions. |
Member
There was a problem hiding this comment.
FWIW - i don't actually care if buganizer numbers leak. They are not sensitive by themselves
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Refines repository authoring and review conventions in
GEMINI.md:Architecture & Module Designto cover both reusing/extending existing subsystem helpers and extracting/unifying shared logic across callers.Commentsguidance to avoid multi-paragraph JSDoc blocks on small helpers, inline comments that restate self-evident code, and repeating the same rationale across functions or tests.Scenarios Tested
Validated
GEMINI.mdformatting and markdown structure.Sample Commands
N/A