Commit Messages

Inspired by the Conventional Commits specification and the Angular convention, ARC-71 uses a commit message structure that consists of a header, a body, and a footer:

<header>

<body>

<footer>

The header is mandatory, while the rest is optional.

Adhering to this convention allows for the possibility of automatically generating changelogs. Note that this project began prior to adopting this specification, so early commits do not adhere to them.

The header line takes the following format:

<type>(<scope>): <description>

The header line should be no more than 72 characters in total. This includes type, scope, description, and relevant delimiter characters. This is to make the commit history easier to read in common tools including git and GitHub.

Type

Type must be one of the following:

  • fix: Issues and bug fixes
  • feat: A new feature
  • docs: Documentation only changes
  • assets: Assets only changes
  • perf: Code changes that improve performance
  • refactor: Restructuring code without introducing new features or fixing bugs
  • style: Changes to code style (e.g. running rustfmt, renaming functions/variables)
  • test: Adding or changing tests
  • chore: Other tasks that don't directly change code, e.g. CI configuration, modifying the build process

Scope

The scope is optional, but strongly encouraged. If the scope is omitted, also omit the parentheses surrounding it, i.e. fix: no longer broken instead of fix(): no longer broken.

Changes to this book (the Game Design Document aka GDD) should have the scope "gdd", and thus all changes to it should be prefixed by docs(gdd): .

chore commits should use the following scopes when appropriate:

  • build: changes to the build process
  • ci: changing the CI/CD process
  • deps: dependencies-only changes (e.g. updating or removing dependencies)

Other scopes are still TBD; for now use best judgment (crate name ­— sans arc71_ prefix — may be a good default) or omit it.

Description

The description is a short summary of the change, using the present imperative, e.g. "change star generation", not "changed" or "changes". It reads as a complete sentence, however it does not start with a capital letter (unless the initial letter would be capitalized otherwise, e.g. proper nouns or initialisms) and does not end with a period.

docs(gdd): add commit message specification

Body

Just like the description, the body uses the present imperative. It is separated from the header by a blank line, and consists of one or more free-form paragraphs separated by blank lines. Use complete sentences and proper grammar.

fix: prevent workers stealing tasks

Introduce a worker ID and apply to tasks as workers take them. Prevent workers
from taking tasks with an ID.

If the body is provided, it should describe more context about the code changes.

If present, the footer contains references to GitHub issues that this commit addresses; it may or may not close the issue, especially for larger issues.

  • On commits that do not close the issue, use Refs, e.g. Refs: #42
  • If the commit closes an issue and is not a fix commit, use Closes, e.g. Closes: #42
  • If the commit closes an issue and is a fix, use Fixes, e.g. Fixes: #42

Commits should address only one issue, however if for any reason a commit does address multiple issues, separate them with commas, e.g. Refs: #42, #56, Refs: #42, Fixes: #78.

Reverting Commits

When reverting previous commits, use revert as the type. The description should summarize what is being reverted, and the body may describe the reason. The footer must contain Refs: followed by the short hashes of the reverted commits. GitHub issue(s) may also be referenced on a separate line.

revert: remove changes to room detection

Turns out these changes are hugely detrimental to performance, so we need to
pull them out for now until those issues can be resolved.

Refs: 676104e, a215868
Refs: #43

Breaking Changes

Generally speaking, a breaking change is any change that would prevent a player from downgrading to the previous version of the code and still keep their current save file.

Breaking changes must be indicated by either a ! immediately before the colon in the header (e.g. feat!: change save file serialization to CBOR) or a footer prefixed with BREAKING CHANGE: followed by a description of the breakage. Both indicators may be present.

Breaking changes need not be indicated prior to the first publicly available build.