Post

Making consistent formatting a constitutional rule instead of a review comment

Making consistent formatting a constitutional rule instead of a review comment

Formatting drift tends to get caught late, by whichever reviewer happens to notice it, and the fix often bundles unrelated whitespace into a functional change. This push promotes formatting to a numbered principle in the project constitution, so the expectation lives in the same place as the repository’s other non-negotiable rules. It is a small documentation change with an outsized effect on how I review and prepare changes.

A sixth principle with named tools

The constitution moves from version 1.0.0 to 1.1.0 and adds principle VI, Consistent Formatting. Rather than a general instruction to keep files tidy, it points at concrete authorities: the repository’s declared formatter, its linter configuration, the Spec Kit Markdown templates for structure, tofu fmt for OpenTofu, and terragrunt hcl fmt for Terragrunt, all wired through pre-commit. Markdown and YAML are linted against the rules under .github/linters/. The other five principles are untouched, so this is an additive amendment rather than a rewrite of prior intent.

What the patch does and does not prove

The visible evidence is confined to the constitution file: 17 added lines and 6 removed. The version history entries are rewritten to reflect the minor bump, and the amendment record drops the earlier reference to the first populated constitution being 1.0.0. This is the rule text and its changelog, not proof that any pipeline enforces it, and it tells me nothing about whether existing files already pass the new expectation. The next check is whether the required CI checks actually run these formatters and whether current Markdown and YAML clear the linter rules without a large cleanup commit.

Scoping formatting edits as a governance property

The most useful clause is the one requiring formatting edits to stay within the scope of the change. That is the difference between a formatter that reduces review noise and one that generates diffs drowning the actual decision. Naming the required CI checks as the authority for merge readiness also moves the judgment out of individual review threads and into something reproducible. For a platform team, the transferable move is treating formatting as an enforceable principle with explicit tools and a scope boundary, so reviews discuss design instead of spacing.

This post is licensed under CC BY 4.0 by the author.