chore: document the comment and commit message rules by balzss · Pull Request #2706 · instructure/instructure-ui

balzss · 2026-09-03T11:21:12Z

Summary

Add a Code comments section to CLAUDE.md, with a human-facing version in the
contributor docs: explain why not what, one line, never reference the change itself.
Fix commitlint.config.js's parserOpts.headerPattern, which couldn't match a scoped
subject like fix(ui-button): ..., so the conventional parser never ran and
subject-max-length applied to nothing. Cap the subject at 100.
Tighten /commit's guidance on commit bodies, and drop the robot attribution line
from commit messages.
Remove ToMESSKa from the /pr reviewer roster — no longer on the team.

Test Plan

subject-max-length: 100 checked against history: 78 of the last 2000 subjects exceed
it, and they're the ones enumerating every package touched instead of naming the change.
Verified the remaining rules still fire — a 120-char subject, a 120-char body line (from
the preset's body-max-line-length) — and that comma scopes like
fix(ui-drawer-layout,ui-a11y-utils): still parse.

Fixes INSTUI-5174

🤖 Generated with Claude Code

github-actions · 2026-09-03T11:26:09Z

PR Preview Action v1.8.1
🚀 View preview at https://instructure.design/pr-preview/pr-2706/
Built to branch `gh-pages` at 2026-09-30 12:51 UTC. Preview will be ready when the GitHub Pages deployment is complete.

github-actions · 2026-09-03T11:30:41Z

Visual regression report

Cypress suite: ✅ Passing

Visual diff: ⚠️ Changes detected.

Status	Count
Unchanged	98
Changed	1
New	0
Removed	0

Accessibility (axe): ✅ No violations.

📊 View full report — click a screenshot's ⚠ badge to see each violation boxed on the image, with the offending element named and contrast failures shown as color swatches.

Diff images (1)

tooltip-light.png — 956 pixels differ

_{Baselines come from the visual-baselines branch. They refresh on every merge to master. The Cypress suite line covers the a11y and console-error assertions — a ❌ there means the suite found real issues even if the visual diff is clean.}

matyasf

What about using the rules here for both commit and PR messages? https://github.com/ayghri/i-have-adhd/blob/main/skills/i-have-adhd/SKILL.md#rules (do not copy it literally, some rules are irrelevant here)

git-nandor · 2026-09-20T19:49:19Z

+- **Never narrate the diff** (`// added onKeyDown handler`, `// updated to support X`) — that's what `git log` is for.
+- No commented-out code, no banner or separator comments, and **don't add comments to code you didn't change**.
+- Lowercase `//` on its own line above what it explains, never trailing. Ticket ids only on a real external blocker: `// TODO INSTUI-1234: <what unblocks it>`.
+- Leave the MIT license header alone — `notice/notice` in `eslint.config.mjs` enforces it.


eslint.config.mjs does not exist, the repo uses .oxlintrc.json

Correct. deed11cc24 replaced ESLint with oxlint. The rule name is the same, only the file changed. Fixed to .oxlintrc.json.

git-nandor · 2026-09-20T19:50:14Z

+Prop docs are a JSDoc block with **one prose sentence** and no `@param`/`@type` — types come from TypeScript and `react-docgen`. See `packages/ui-alerts/src/Alert/props.ts`.
+


Alert/props.ts — broken reference, missing v1/v2

The real paths are Alert/v1/props.ts and Alert/v2/props.ts, but neither fits. Several v2 props have multi-paragraph JSDoc. I removed the example and kept the rule.

balzss · 2026-09-24T14:11:10Z

@matyasf That skill is about chat responses. Four of its 10 rules are already here, five do not apply to commits, and "number multi-step tasks" conflicts — that is the changelog body this PR removes.

joyenjoyer · 2026-09-25T12:24:41Z


-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-
 Co-Authored-By: Claude <noreply@anthropic.com>


In the PR description you claim drop the robot attribution line from commit messages.

I may consider removing the Co-Authored-By line too.

i wanted to keep it for transparancy's sake, we can discuss later if we want to get rid of it completely

joyenjoyer · 2026-09-25T12:29:38Z

+
+### Body
+
+**Omit the body when the subject says it all.** When you do write one, it explains **why** — the constraint, the cause, the thing the diff cannot show. Never restate what changed.


I am not sure that any model is smart enough to understand the first sentence, how do they interpret "the subject says it all"? I think this is too abstract.

I would add two real life examples that help Claude's pattern recognition:

if the commit message title is straightforward

if it does not and therefore further explanation is needed in commit body

Claude derives patterns from examples easier than from general statements.

added some examples

joyenjoyer · 2026-09-25T12:33:02Z

+- **Never reference the change itself.** `now`, `new`, `previously`, `used to`, `this change`, `the fix`, `as discussed`, `per review`, `we decided`, `recently` — these only mean something next to the diff. Name the constraint instead.
+- **Never narrate the diff** (`// added onKeyDown handler`, `// updated to support X`) — that's what `git log` is for.
+- No commented-out code, no banner or separator comments, and **don't add comments to code you didn't change**.
+- Lowercase `//` on its own line above what it explains, never trailing. Ticket ids only on a real external blocker: `// TODO INSTUI-1234: <what unblocks it>`.


I saw Claude adding ticket references for other products' tickets from their JIRA board, I believe we should not allow this, it should only reference our tickets.

good call, added guardrails

The rules live in two places so they hold whichever way someone arrives: CLAUDE.md for an agent session, docs/contributing for a human contributor. commitlint's headerPattern could not match a scoped subject like `fix(ui-button): ...`, so the conventional parser never ran and subject-max-length applied to nothing. Dropping the pattern lets the parser work, and the cap drops from 150 to 100 - 78 of the last 2000 subjects were over 100, and those are the ones listing every package touched instead of naming the change. Co-Authored-By: Claude <noreply@anthropic.com>

No longer on the team, so /pr should stop offering them as a reviewer. Co-Authored-By: Claude <noreply@anthropic.com>

balzss self-assigned this Sep 3, 2026

github-actions Bot pushed a commit that referenced this pull request Sep 3, 2026

visual-regression: PR #2706 (53ba49c) 53ba49c

d74a258

github-actions Bot pushed a commit that referenced this pull request Sep 4, 2026

visual-regression: PR #2706 (87633ad) 87633ad

2e68695

balzss force-pushed the chore/commit-comment-wording branch from 9d02c38 to 196c515 Compare September 7, 2026 07:49

github-actions Bot pushed a commit that referenced this pull request Sep 7, 2026

visual-regression: PR #2706 (3eaad2b) 3eaad2b

aa50afc

balzss force-pushed the chore/commit-comment-wording branch from 196c515 to f03ab99 Compare September 14, 2026 16:20

github-actions Bot pushed a commit that referenced this pull request Sep 14, 2026

visual-regression: PR #2706 (f537929) f537929

ec9c60d

balzss changed the title ~~chore: document comment rules and enforce commit message shape~~ chore: document the comment and commit message rules Sep 16, 2026

balzss requested review from git-nandor and matyasf September 16, 2026 11:52

matyasf requested changes Sep 17, 2026

View reviewed changes

Comment thread .claude/commands/commit.md Outdated

git-nandor reviewed Sep 20, 2026

View reviewed changes

git-nandor requested changes Sep 20, 2026

View reviewed changes

balzss force-pushed the chore/commit-comment-wording branch from f03ab99 to 2df4178 Compare September 24, 2026 13:49

github-actions Bot pushed a commit that referenced this pull request Sep 24, 2026

visual-regression: PR #2706 (f84c15d) f84c15d

58c9e25

balzss requested review from git-nandor, joyenjoyer and matyasf September 24, 2026 14:08

joyenjoyer requested changes Sep 25, 2026

View reviewed changes

matyasf approved these changes Sep 28, 2026

View reviewed changes

git-nandor approved these changes Sep 29, 2026

View reviewed changes

balzss and others added 2 commits September 30, 2026 14:47

chore: remove ToMESSKa from the reviewer roster

1502609

No longer on the team, so /pr should stop offering them as a reviewer. Co-Authored-By: Claude <noreply@anthropic.com>

balzss force-pushed the chore/commit-comment-wording branch from 2df4178 to 1502609 Compare September 30, 2026 12:49

github-actions Bot pushed a commit that referenced this pull request Sep 30, 2026

visual-regression: PR #2706 (f0f84dd) f0f84dd

d61c1bc

balzss requested a review from joyenjoyer September 30, 2026 14:10

		Prop docs are a JSDoc block with one prose sentence and no `@param`/`@type` — types come from TypeScript and `react-docgen`. See `packages/ui-alerts/src/Alert/props.ts`.


		🤖 Generated with [Claude Code](https://claude.com/claude-code)

		Co-Authored-By: Claude <noreply@anthropic.com>


		### Body

		Omit the body when the subject says it all. When you do write one, it explains why — the constraint, the cause, the thing the diff cannot show. Never restate what changed.

Conversation

balzss commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

github-actions Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-09-30 12:51 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

github-actions Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Visual regression report

tooltip-light.png — 956 pixels differ

Uh oh!

matyasf left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

balzss commented Sep 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joyenjoyer Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

balzss commented Sep 3, 2026 •

edited

Loading

github-actions Bot commented Sep 3, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-09-30 12:51 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

github-actions Bot commented Sep 3, 2026 •

edited

Loading

matyasf left a comment •

edited

Loading

joyenjoyer Sep 25, 2026 •

edited

Loading