docs(qa): mandate clickable refs, [~] mentions, and explicit F1.5 - #35
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the QA review guidelines by introducing Note F1.5 to the checklist, which mandates explicitly recording summary, description, and scope currency. It also adds guidelines to the comment template regarding clickable references, user mentions, and escaping block-markup tags. The reviewer suggested adding a bullet point prefix to the F1.5 example verdict in the checklist to ensure formatting consistency with the comment template.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Round-1 QA comments (especially machine-generated ones) kept emitting bare
`group/project!N`, `pipeline N`, `PR N`, tag and commit references that are
plain text in Jira, and plain person names instead of `[~username]` mentions
(including the customer-handover greeting). The linkability guidance existed but
was under-emphasised and had no person-mention rule.
- comment-template.md: new sanity-scan items 3a (bare refs are not clickable in
Jira, wrap every MR/PR/pipeline/tag/SHA as `[shorthand|url]`, scan the whole
comment) and 3b (every named person must be a `[~username]` mention, incl. the
handover greeting); extend item 7 to cover machine-/sub-agent-generated
comments escaping literal `{code}` at generation time.
- checklist.md: Note F1.5 — record the description-currency/scope verdict
explicitly in every QA comment even when it passes, and require it per
sub-agent when the review is fanned out.
Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
1712880 to
95c4cb0
Compare
|
What
Strengthen the Round-1 QA comment guidance so references and person names are always clickable/mentioned, and the description-currency check is never silently skipped.
comment-template.md: new sanity-scan items 3a (baregroup/project!N,owner/repo#123,pipeline N,PR N, tags and short SHAs are plain text in Jira — wrap every one as a[shorthand|url]macro and scan the whole comment, not just F4b) and 3b (every named person must be a[~username]mention, never a plain display name — including the customer-handover greeting). Item 7 extended to machine-/sub-agent-generated comments escaping literal{code}at generation time.checklist.md: Note F1.5 — record the description-currency/scope verdict explicitly in every QA comment even when it passes, and require it per sub-agent when the review is fanned out.Why
A batch of maintenance QA comments (largely machine-generated) shipped bare
!373/pipeline 233639/PR 6428references that don't click in Jira, a handover addressed to a plain first name instead of a mention, and F1.5 recorded on only 2 of 8 tickets. The linkability guidance existed but was under-emphasised and had no person-mention rule.Docs-only; no version bump.