Skip to content

commit-conventions.md

Latest commit

 

History

History
102 lines (76 loc) · 3.01 KB

commit-conventions.md

File metadata and controls

102 lines (76 loc) · 3.01 KB
Raw

Commit Conventions

Standard

Use Conventional Commits for all repository changes:

<type>(<optional-scope>): <title>

The scope is optional. Use it only when it identifies a stable subsystem such as editor, catalog, sprites, or docs.

Types

Type Purpose
feat Introduces user-visible functionality.
fix Corrects defective behavior.
docs Changes documentation only.
refactor Changes implementation without changing behavior.
perf Improves runtime performance.
test Adds or changes verification code.
build Changes build or dependency tooling.
ci Changes continuous-integration configuration.
chore Performs repository maintenance not covered above.
revert Reverts an earlier commit.

Title rules

  • Write titles in English.
  • Use the imperative mood and present tense.
  • Start the title with a lowercase letter.
  • Do not end the title with punctuation.
  • Keep the title concise and specific.
  • Describe one logical change per commit.
  • Do not include issue identifiers unless they add necessary context.
  • Do not add generated coauthor trailers.

Examples:

feat(editor): add rectangular selection duplication
fix(catalog): preserve unnamed item records
docs: define map document format
refactor(editor): isolate mark derivation
chore: update repository metadata

Commit body

Prefer a title-only commit when the change is self-explanatory. Add a body only when reviewers need context that cannot be expressed by the diff and title. When present, the body must explain motivation, constraints, or compatibility impact rather than repeat implementation details.

Do not add Co-authored-by trailers unless a human contributor explicitly requests attribution for substantive work.

Breaking changes

Append ! to the type or scope and include a BREAKING CHANGE: footer when a change requires consumers to migrate:

feat(format)!: replace legacy collision arrays

Map document schema changes must also increment the exported format version and document the migration in docs/map-format.md.

Branches

Create short-lived branches from main. Use lowercase, hyphenated names with a category prefix:

feat/selection-tools
fix/catalog-flags
docs/map-format
chore/repository-settings

Keep branches focused, rebase or merge the current main before integration, and remove branches after merge.

Pull requests

  • Use a semantic title that follows the commit title format.
  • Explain the purpose, technical impact, and verification performed.
  • Keep unrelated changes in separate pull requests.
  • Confirm that generated artifacts match their source inputs.
  • Resolve review comments before merge.
  • Use squash merge when a branch contains intermediate commits that should not remain in the permanent history.

Repository history

Do not commit secrets, credentials, local configuration, temporary files, or unrelated generated assets. Review staged files and the final commit message before every push.