ContextQMD
Back to Chromium

Accessibility Cleanup Bug Tracking Guidelines

agents/projects/code-health/accessibility-cleanup/references/bug_discovery.md

151.0.7891.13.5 KB
Original Source

Accessibility Cleanup Bug Tracking Guidelines

Use these instructions to find or create a tracking bug for accessibility cleanup tasks.

The Discovery Query

CRITICAL MANDATE: You MUST use the mcp_Coding_internal_search tool (Moma) for ALL discovery and verification. NEVER use mcp_Buganizer_get_bugs or get_bugs for this process, as they redact Chromium issues and return unrelated internal bugs.

Use this exact pattern in Moma: "[Accessibility Cleanup]" "Improve accessibility semantics in" "<SourceFileName>" status:open

  • <SourceFileName>: The full name of the Java file with the accessibility issue.

Discovery

If an existing bug is found for this file, and the status of the bug is open, all efforts for the <SourceFileName> should be abandoned because we have a signal that a previous agent is likely already addressing this bug and we should wait for that effort to finish before starting a new effort for this file.

If an issue does not exist, proceed to creation.

Creation

  1. LDAP Retrieval: Determine the current user's LDAP using run_shell_command (whoami)
  2. Bug Creation: Create a Buganizer issue using the relevant tools (e.g. mcp_Buganizer_create_buganizer_issue). Bug information:
    • Component ID: 1456931 (CodeHealth).
    • Hotlist IDs: 8218789 and 8519218
    • Assignee: <LDAP>
    • Title: [Accessibility Cleanup] Improve accessibility semantics in <SourceFileName>
    • Description: See the "Description construction" section below for full details on how to construct the description of the bug.
  3. Capture ID: Capture the returned Bug ID for use in the commit message footer (e.g. Bug: <BugID>).

Description construction

The description of a bug will consist of three parts:

  1. Mandatory disclaimer / header
  2. Explanation of the accessibility violation
  3. Steps to reproduce / test the presence of the violation in the app

Mandatory disclaimer / header

Every bug opened MUST start with the following disclaimer / header:

*"Note: This bug was automatically generated by the Chrome Code Health AI."*`.

This bug is to address violations of accessibility semantics or API expectations
in the file: <SourceFilePath>.

Explanation of the accessibility violation

Provide a detailed explanation of the accessibility violation that has occurred and why this is a poor design. Example:

File <SourceFileName> is concatenating text of the form "Click to expand" to the
end of the contentDescription of the View FooBar. This is a poor design as it
does not communicate to the Android Accessibility Framework that a node is
expandable, and relies on the text announcement of a screen reader (e.g.
TalkBack) to communicate this to the user. This means non-TalkBack users, such
as those using VoiceAccess, are unaware that this node is expandable.

The correct approach is to explicitly add the `ACTION_EXPAND` and
`ACTION_COLLAPSE` AccessibilityActions to the AccessibilityNodeInfo object of
the View, and allow the downstream accessibility services to handle the user
experience given that semantic information.

Steps to reproduce

Provide detailed steps of how to reproduce the issue on a regular build. The section should be in a format similar to:

Prerequisites:
Enable the following flag:
> Flag one, Flag two, Flag three, etc

Steps to reproduce:
1. Open Chrome
2. Perform foo
3. Perform bar
4. Perform baz

Expected outcome:

The foo bar baz feature should behave in this way.

Observed outcome:

The foo bar baz feature did this behavioral violation.