Commit messages

When suggesting or writing commit messages for this repo, follow these rules.

Format

• Use Conventional Commits. Prefer the form type(scope): description or type: description. Keep the type to a set that tools like Release Please recognise: feat, fix, docs, style, refactor, perf, test, build, ci, chore. Scope is optional; use it when it helps (e.g. feat(graphql):, fix(data-sourcing):).
• Subject line: Imperative mood, lowercase after the colon. Write it so it would make sense in a changelog on its own (e.g. feat: add whitelisting_rules query not feat: added whitelisting_rules query or feat: Adding the whitelisting rules query).
• Jira/ticket refs: Only reference a ticket (e.g. SIM-652) in the subject or body if this commit fully resolves that ticket. Otherwise omit.
• Merge commits: Leave merge commit messages as-is; do not rewrite them.

Body

• When to add a body: Only for non-trivial commits. Small, obvious changes do not need a body.
• Style: Prefer short, concise bullet points. Focus on what matters to the end user or to the project’s architecture; avoid narrating every file or line changed.
• Length: Keep the message reasonable. Nobody wants to read an essay.

Examples

Good (subject only):

• feat(graphql): add whitelisting_rules query
• fix: upgrade OpenSSL in Docker images to fix CVE-2025-69421
• chore: add dependency on ddtrace

Good (with body for non-trivial change):

refactor(graphql): split schema into domain modules

- common.py: GlobalID, Blob, PageInfo, Connection, decode_id
- culling.py: CulledDocument, get_culled_documents, WhitelistingQuery
- documents.py: Document, Filters, DocumentsQuery
- schema.py: composes Query, schema, graphql_app

Public API unchanged.

Avoid:

• Past tense or sentence case in subject: Added foo, Updates the bar
• Ticket ref when the commit doesn’t close the ticket
• Long, story-style bodies for trivial changes
• Capitalised word after the colon (except proper nouns)
• Do not mention that a commit was co-authored by Cursor in the commit message or trailer.