lint-sync

Code Health: Lint Sync Guards

Identify enums in the codebase that are persisted to logs (e.g., recorded in enums.xml) but are missing the LINT.IfChange(...) and LINT.ThenChange(...) guards that enforce synchronization between the source code and the XML metadata.

Overview

When developers modify an enum in C++ or Java but forget to update the corresponding entry in enums.xml, it breaks downstream metrics pipelines. Adding IfThisThenThat lint guards prevents this by generating Gerrit warnings if one side is modified without the other. Act as an expert Chromium contributor to add these missing guards.

Goal: Add LINT.IfChange/ThenChange sync guards to enums in C++/Java and XML files to enforce synchronization.

Relevant Resources & Style Guides

• Chromium IfThisThenThat (IFTTT) Guides
• Discovery Script: find_candidates.py
• Implementation Patterns: patterns.md (Syntax rules and examples)
• Automated Review Protocol: automated_review.md

Workflow

[!IMPORTANT] Execution Protocol: Execute all steps sequentially one by one. Do not skip any step. Do not use edit-code or grep. Use rg (ripgrep) for searches.

Step 1: Workspace Preparation

Follow the workspace preparation steps in workspace_preparation.md to ensure a clean and updated environment.

Step 2: Discovery & Batch Selection

Follow the Discovery & Batch Selection workflow.

Step 3: Refactoring & Implementation

Process the candidates by handling them one file at a time, and applying modifications inside each file one enum at a time (rather than refactoring all files or enums at once). This ensures stability and allows for precise verification. Refer to patterns.md for sync guard syntax rules and examples before making replacements.

1. Process Enum: For each enum in the list:

   • Sync Verification: Delegate to the generalist sub-agent with this exact prompt:

     "Compare the enum <EnumName> in <SourcePath> with its metadata entry in <XMLPath>. Verify that all valid enum entries in the source have corresponding <int value="..." label="..."> entries in the XML. IMPORTANT: Ignore/skip sentinel values like kMaxValue, kCount, COUNT, or NUM_ENTRIES in the comparison; they are not expected to be in the XML. Return 'SYNCED' or a concise list of missing entries that need to be added to the XML. Ensure any suggested labels reflect the enum constant name and any suggested tags are concise descriptions of the enum's purpose."

   • Fix & Proceed: If the generalist returns missing entries, add them to the XML file before proceeding with the guards. Only append missing entries to the XML. Never modify existing names or values in either file. Do not shift the numeric values of an enum. When adding new values to the XML enum, check the format of the existing <int> entries and ensure new entries match that format. Labels added to the XML MUST be concise (matching the enum constant name) and any tags MUST be brief descriptions of what the enum tracks.
   • Source:
     • Append-Only Logging Comment: Check if the enum's preceding comment already contains a warning about append-only histogram logging. If it does not, add the standard Chromium metric comment: // These values are persisted to logs. Entries should not be renumbered and numeric values should never be reused.
     • Clean up legacy sync comments (CRITICAL): Search the enum's preceding comments for manual synchronization reminders (e.g., // Please keep in sync with... or // Always keep this enum in sync with...). Remove ONLY the specific sentence or line referencing the manual synchronization. Preserve all other parts of the comment (e.g., descriptions of what the enum represents, renumbering warnings, or usage instructions). If the entire comment block only contains a sync reminder, the whole block may be removed.
     • Add // LINT.IfChange(<SourceName>) immediately before the enum definition.
     • Add // LINT.ThenChange(<XML Path>:<XmlName>) immediately after the enum.
   • XML:
     • Add the <!-- LINT.IfChange(<XmlName>) --> immediately before the <enum> tag.
     • Add <!-- LINT.ThenChange(<Source Path>:<SourceName>) --> immediately after the </enum> tag.
   • Handling Mismatched Names: If the name in the Source file (SourceName) differs from the name in the XML file (XmlName), ensure the correct name is used in each respective IfChange and ThenChange tag as shown in the Syntax Rules.

2. Iterate: Once the enum is fully synced and verified, move to the next one in the list and repeat. Do not attempt to batch multiple enums in a single file-write operation to ensure accuracy. Once all enums have been processed, proceed immediately to the Review & Validation phase.

Step 4: Validation

1. Linting & Formatting:
   • XML Linting: Execute python3 tools/metrics/histograms/validate_format.py to validate all metadata changes. Address any errors that are reported.
   • Code Formatting: Execute git cl format to format the modified source code. Address any errors that are reported.
2. Mandatory Final Review: Follow the Automated Review Protocol to delegate a final review of the patch to the generalist sub-agent. Proceed to the Verification phase only after the review returns PASS.

Step 5: Verification

Follow the Verification workflow.

Step 6: Submission

Invoke the Submission workflow. Pass the following context variables to the workflow:

• Skill Name: lint-sync
• Branch Name: lint-sync-<EnumName>
• Commit Hashtag: lint-sync
• Cleanup Title: Add missing LINT guards in <SourceFilePath>
• Cleanup Description: Adding IfThisThenThat lint guards to ensure synchronization between the following source code enums and their metadata representation in enums.xml: <EnumNamesList (comma-separated)>
• Parent Bug: 498775295
• Cleaned Component: The source file path.
• File Count: Number of files modified.