Skip to content

chore: document the comment and commit message rules - #2706

Open
balzss wants to merge 2 commits into
masterfrom
chore/commit-comment-wording
Open

balzss wants to merge 2 commits into
masterfrom
chore/commit-comment-wording

Conversation

@balzss

@balzss balzss commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

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

@balzss balzss self-assigned this Sep 3, 2026
@github-actions

github-actions Bot commented Sep 3, 2026

Copy link
Copy Markdown
Contributor
PR Preview Action v1.8.1

QR code for preview link

🚀 View preview at
https://instructure.design/pr-preview/pr-2706/

Built to branch gh-pages at 2026-09-14 16:24 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

@github-actions

github-actions Bot commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Visual regression report

Cypress suite: ✅ Passing

Visual diff: ⚠️ Changes detected.

Status Count
Unchanged 93
Changed 3
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 (3)

badge-canvas.png — 1573 pixels differ

tooltip-dark.png — 881 pixels differ

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.

github-actions Bot pushed a commit that referenced this pull request Sep 3, 2026
github-actions Bot pushed a commit that referenced this pull request Sep 4, 2026
@balzss
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
balzss and others added 2 commits September 14, 2026 18:18
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
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
@balzss balzss changed the title chore: document comment rules and enforce commit message shape chore: document the comment and commit message rules Sep 16, 2026

@matyasf matyasf left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

the way an external consumer would.
```

Writing about _before_ and _after_ is encouraged — "Previously the placeholder only showed on hover" is exactly right in a commit message, which is permanently anchored to its own diff. (Code comments are different: see CLAUDE.md.)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no need for this part:
"(Code comments are different: see CLAUDE.md.)"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants