Gerrit Code Review

The gerrit-commit-message-review skill defines the engineering standards for formatting, structuring, and preserving metadata within Git commit messages. The standards are divided into four main areas:

1. Commit Title Conventions: Stylistic and length requirements for the first line to optimize history navigation.
2. Commit Body Structure & Formatting: Instructions for explaining the "what" and "why" of a patchset with conciseness and precise wrapping.
3. Metadata Footers & Preservations: Strict enforcement of preserving system-critical integration footers like Change-Id and issue tracking IDs.
4. Review Feedback & Suggested Commit Message: Requirement for reviewers to provide a complete, fully-compliant, and copy-pasteable revised commit message.

The @gerritcodereview/typescript-api package provides the types, interfaces, and enums required to develop browser plugins for the Gerrit Code Review web application.

While the .ts files contain the full type definitions, the compiled .js files only contain the enums. For JavaScript-only plugins, this package is primarily useful as a source of truth for supported plugin APIs. For TypeScript development, it provides the necessary type safety for interacting with the Gerrit web application.

For comprehensive guidance on plugin development, refer to the official Gerrit Plugin Development documentation.

Gerrit uses NoteDb (Git notes) to persist change metadata. To guarantee data integrity during distributed cluster upgrades, follow these strategies:

• Two-step schema rollouts: Implement changes in stages to ensure compatibility.
• Decoupled transfer objects: Use dedicated objects for data transfer to separate the persistence model from the application model.
• Permissive JSON parsing: Ensure parsers can handle evolving schemas without failing.

The project is in a gradual migration from yarn to pnpm.

Critical Rules:

• yarn.lock is the authoritative source of truth.
• pnpm-lock.yaml is generated via pnpm import and must NOT be edited manually.
• DO NOT RUN pnpm install, as it creates a different dependency graph than what is expected.

Standard Workflow:

1. Edit package.json
2. Run yarn install
3. Run bazel build gerrit
4. If the build indicates the lock file was updated, rerun the build command.

Avoid 'pedantic noise' by adopting a high threshold for flagging issues. Do not suggest rewrites for minor stylistic preferences or trivial variations if the message is already clear, informative, and meets core requirements.

Do NOT flag:

• Minor casing differences (e.g., GrepServlet: add ... vs GrepServlet: Add ...).
• Subjective phrasing or sentence structure preferences.
• Trivial stylistic points that do not impact readability.

DO flag:

• Objective violations: Title > 60 characters, body lines > 72 characters, missing essential context, or corrupted/missing metadata footers.

Initialize base reactive properties during construction or via willUpdate. Avoid using the firstUpdated hook for initial assignments, as it triggers an unnecessary second render cycle and hurts initial paint performance.

// GOOD: Reactively bound to updates before render
override willUpdate(changedProperties: PropertyValues) {
  if (!this.hostUrl) {
    this.hostUrl = window.location.origin;
  }
}

To conserve bandwidth in objects that support impersonation (such as ReviewerUpdateInfo), you must omit the real_updated_by field if it is identical to the primary updated_by field. Instead of duplicating the user object, set the field to null to signal that no impersonation has occurred.

Applies to: REST API serialization layers, specifically ChangeJson.java and TypeScript interface definitions.

// GOOD: Return null to omit the field entirely
new ReviewerUpdateInfo(
  c.date(),
  accountLoader.get(c.updatedBy()),
  c.realUpdatedBy().map(accountLoader::get).orElse(null),
  ...
);

To ensure system resilience against future metadata schema expansions, all JSON parsers reading NoteDb revision notes must be inherently permissive. They must safely ignore unknown fields during deserialization to avoid Parsing Exceptions when new fields are added to the payload.

Implementation: Use a permissive JSON parser configuration (e.g., Gson with default settings) that does not throw exceptions when encountering undocumented properties.

// GOOD: Permissive parsing explicitly ignoring unknown fields + regression tests verifying this behavior
Gson permissiveGson = new GsonBuilder().create();
RevisionNoteData data = permissiveGson.fromJson(reader, RevisionNoteData.class);

Always bind event listeners directly within the render() template using the @event syntax. Do not use this.addEventListener inside the component constructor, as this disconnects logic from the template and risks memory leaks.

// Do:
override render() {
  return html`
    <div class="menu" @mousedown=${this.handleMenuMouseDown}>
      <div class="menu-item">${this.hoverCardText}</div>
    </div>
  `;
}

When dealing with deleted or recreated user accounts, implement constraints to prevent identity-cycling exploits:

• Validation Isolation: Isolate validation checks for user identities.
• Orphaned Approval Filtering: Filter orphaned approvals during merge operations to ensure security without degrading system performance.