TheRock/rocm-libraries/docs/LIBRARIES_PR_BOT_FAQ.md

Libraries PR Bot — Policy FAQ Doc

Libraries PR Bot is an automated Pull Request (PR) gatekeeper. On every Pull Request, it runs a set of policy checks — branch naming, title/description, forbidden files, unit tests, and required CI checks — then posts a single results table comment summarising what passed or failed. PRs that fail key checks are flagged with a Not ready to Review label until the issues are resolved.

It helps save time on the first level of PR review by automating the basic checks a reviewer would otherwise perform manually, reducing first-pass review time. Reviewers can filter out Not ready to Review PRs from their pending review list and only start reviewing once that label has been removed — i.e. once all policy checks have passed.

This document explains what each policy check means, why it exists, and how to fix a failure.

Note: This is NOT an AI Bot and does not use any LLMs. It is a deterministic, rule-based checker driven entirely by policy.yml.

---

🌿 Branch Name

What does it check? Your branch name must follow the agreed naming convention so PRs are easy to trace back to a contributor and topic.

Allowed formats

Pattern	Example
users/<username>/<anything>	users/dgaliffi/fix/remove-build-boost-option
users/<username>/<anything>	users/frepaul/ROCm-end-user-project-workflow
shared/<anything>	shared/add-runner-health
<single-segment-name>	bump-rocm-libraries-936a6c7
<single-segment-name>	ZIP-packaging-RFC
dependabot/<anything>	dependabot/github_actions/github-actions-3dfd2199fc
revert-<pr-number>-<anything>	revert-5217-users/derobins/add_hipfile_support

Rules:

• A recognised prefix must be present (users/, shared/, dependabot/, revert-…) — or the branch must be a single segment.
• Uppercase letters are allowed (acronyms and module names are common, e.g. ROCm, SMP, RFC).
• For users/, the <username> segment may contain letters (upper or lower), digits, and hyphens.
• Anything after the prefix is allowed, including nested namespace/feature paths (e.g. users/dgaliffi/fix/remove-build-boost-option).

How to fix Rename your branch before opening the PR:

git branch -m old-name users/<your-username>/<topic>
git push origin -u users/<your-username>/<topic>

---

📝 PR Title

What does it check?

Note: In the results table, the title and description checks are reported together as a single PR Title/Description row. Any title or description failure shows up there.

Length rules (only)

• Minimum: 10 characters
• Maximum: 100 characters

The title is validated by length only. There is no enforced format (e.g. Conventional Commits) and no forbidden-word list — any wording is accepted as long as it is 10–100 characters long.

How to fix Edit the PR title on GitHub (top of the PR page → pencil icon) so it is between 10 and 100 characters, e.g.:

Add token refresh support
Correct codeql workflow trigger

---

📄 PR Description

What does it check? The PR body (description) must be at least 30 characters long and reference a tracking item (JIRA ID or ISSUE ID). An empty or one-line description makes it hard for reviewers to understand the context.

Required tracking reference — include one of the following. Type the line exactly as shown, without surrounding backticks:

Type	Example
JIRA ID	JIRA ID : TESTAUTO-6039
JIRA ID	JIRA ID - #330
JIRA ID	JIRA ID #330
ISSUE ID	ISSUE ID : TESTUTO-3334
ISSUE ID	ISSUE ID - TESTAUTO-3433
ISSUE ID (link)	ISSUE ID : https://github.com/abc/abc_repo/issues/1234
Closing keyword	Closes #10
Closing keyword	Fixes octo-org/octo-repo#100
Closing keyword	Resolves: #123
GitHub issue	#123
GitHub issue URL	https://github.com/abc/abc_repo/issues/123

Note: For JIRA ID / ISSUE ID, the separator is optional and may be : or - (ISSUE ID #330, ISSUE ID : #330, and ISSUE ID - #330 all work). Each accepts a JIRA key (PREFIX-<number> — any project), a number (with or without #), or a link.

Closing keywords (case-insensitive, optional colon): close / closes / closed, fix / fixes / fixed, resolve / resolves / resolved — followed by #<number> or <org>/<repo>#<number>.

How to fix Edit the PR description and explain:

• What changed and why.
• A tracking reference from the table above (required) — e.g. a JIRA ID : / ISSUE ID : line, a Closes #123, or a plain #123.
• Testing steps if applicable.

---

📏 PR Size

What does it check? Large PRs are hard to review thoroughly.

Note: PR size limits are not currently enforced by policy.yml (there are no max_files_changed / max_total_changes / max_single_file_changes values configured). This section is guidance only and the bot does not fail a PR on size today.

Recommended guidance Split your work into smaller, focused PRs. Each PR should ideally do one thing:

• One feature, one fix, or one refactor — not all three at once.
• Move large auto-generated or vendored file changes to a separate PR.

---

⛔ Forbidden Files

What does it check? Certain file types must never be committed to the repository because they can expose secrets or introduce security risks.

Pattern	Reason
**/*.pem	TLS/SSL certificates — must not be stored in source control
**/*.key	Private keys — must not be stored in source control
**/.env	Environment files — often contain secrets/passwords
**/*.exe	Windows executables — binary blobs with no review value
**/*.crt, **/*.cer, **/*.der	Certificates — must not be committed
**/*.p12, **/*.pfx	Keystores / certificate bundles — contain secrets
**/*.csr	Certificate signing requests — should not be in source control
**/id_rsa, **/id_dsa, **/id_ecdsa, **/id_ed25519	SSH private keys
**/*.gpg, **/*.asc	GPG keys / signatures — must not be committed

How to fix Remove the file from your commit:

git rm --cached path/to/secret.pem
echo "*.pem" >> .gitignore
git commit --amend

If a secret was already committed, rotate it immediately and follow your organization's incident response process.

---

🧪 Unit Test

What does it check? PRs that change real source code must include at least one accompanying unit test.

Rules

• Doc / config-only PRs are exempt. If your PR only touches files like .md, .txt, .yml, .yaml, .ini, the check passes automatically — no test required.
• Code PRs require a test. If your PR changes source files such as .py, .cpp, .cc, .c, .h, .js, .ts, .go, .java, it must also include changes to a test file (a new test, or edits to an existing one).

What counts as a test file?

Pattern	Example
test_*	test_parser.py
*_test.*	parser_test.py
*_gtest.*	matmul_gtest.cpp

=======

• Basename matches one of: test_*, testing_*, *_test.*, *_tests.*, or Test*
  • ✅ test_parser.py, testing_parser.py, parser_test.cpp, parser_tests.cpp, TestUtils.cpp
  • ❌ test.py (does NOT have the test_ prefix)

Pattern	Example
test_*	test_parser.py
testing_*	testing_parser.py
*_test.*	parser_test.cpp
*_tests.*	parser_tests.cpp
Test*	TestUtils.cpp

Path-based recognition Any file located under a test/gtest/ directory is also treated as a unit test, regardless of its filename — e.g. projects/miopen/test/gtest/unit_conv_solver_ConvWinoRageRxS.cpp.

How to fix Add a unit test for the code you changed, named to match one of the patterns above (for example test_<something>.py or <something>_gtest.cpp):

# example for Python
touch tests/test_my_feature.py

---

🔎 pre-commit

What does it check? All pre-commit hooks defined in .pre-commit-config.yaml must pass. This typically includes linting, formatting (black, isort), and other code-quality checks.

How to fix Run the checks locally, let them auto-fix where possible, then commit the result:

python -m pip install pre-commit
pre-commit install
pre-commit run --all-files --show-diff-on-failure
git add -u
git commit -m "chore: apply pre-commit fixes"

---

🔎 CodeQL

What does it check? GitHub's CodeQL static-analysis engine scans the code added in this PR for known security vulnerabilities. The bot fails this check when CodeQL reports critical, high, or error-severity alerts.

Common findings include:

Alert	Meaning
py/command-line-injection	User input passed unsanitised into a shell command
py/sql-injection	User input concatenated into a SQL query
py/flask-debug	Flask app started with debug=True on a public interface
js/xss	User input rendered unescaped into HTML

How to fix

1. Open Security → Code scanning alerts on the repository page.
2. Read the alert details and the suggested fix.
3. Apply the fix (validate/sanitise input, use parameterised queries, disable debug mode, etc.).
4. Push the fix — CodeQL will re-run and the alert will be resolved.

Tip: GitHub Advanced Security AI comments directly on the offending line with a suggested code change.

---

🌿 Bump PRs (Automated Dependency Updates)

What is a "Bump PR"?

A Bump PR is an automated pull request that updates dependencies (e.g. from Dependabot or a bot like assistant-librarian). These PRs are routine, high-volume, and do not follow the standard PR conventions.

Why did my Bump PR skip policy checks?

When a PR is detected as a bump update from a configured bot account (e.g. @assistant-librarian[bot]), all policy checks are auto-approved. This includes:

• Branch name validation
• PR title (length) check
• JIRA/ISSUE ID reference requirement
• Unit test requirement
• And all other policies

This keeps automated bots from being blocked by human-oriented policy gates and prevents spam of "Not ready to Review" labels.

How does the bot know it's a Bump PR?

The PR author's login is checked against a configured list of bump bot accounts. Currently recognized:

• assistant-librarian (and assistant-librarian[bot])
• systems-assistant (and systems-assistant[bot])

If a different bot opens dependency-bump PRs in your repo, request that the maintainers add it to bump_bot_authors in policy.yml.

---

General Questions

Why did my PR get the "Not ready to Review" label?

The label is added when:

1. Unit Test check fails — your PR changes source code but has no accompanying test file.
2. JIRA/ISSUE ID reference is missing — your PR description does not include a tracking reference.

All other policy failures (branch name, title format, description length, forbidden files, etc.) do not add the label; they are still reported in the table but do not block the PR.

What is the "Not ready to Review" label?

When PR Title/Description, Unit Test, or Forbidden Files fails, the bot adds a Not ready to Review label to the PR so it is clearly gated. The label is removed automatically once all policy checks pass. Other failures (Branch Name, PR Size, Draft PR, pre-commit, CodeQL) do not add the label.

How are pre-commit and CodeQL shown?

These run as separate CI workflows. The bot waits for them and folds their results into the same table — pre-commit and a single combined CodeQL row. The CodeQL row fails if CodeQL reports any error / critical / high severity alert.

The bot timed out — what do I do?

If pre-commit or CodeQL takes longer than 15 minutes, the bot times out. Push an empty commit to re-trigger the workflow or close and reopen PR:

git commit --allow-empty -m "ci: retrigger policy check"
git push

How do I re-run the bot after fixing issues?

Push any commit (including --allow-empty) to the PR branch. The synchronize event triggers a fresh policy check automatically.

---

🙋 Wish to Override the Policy Process and get unblocked?

Contact CODEOWNERS or supporters channel - (DevOps - Support or Help)

🙋 For any policy related feedback?

please reach out to the ROCm Policy Council.

📧 Drop a mail to: rocm-repo-policy@amd.com (ROCm Policy Council DLL)

Include your PR link, the check(s) you want overridden, and a short justification so the council can review your request.

---