Page MenuHomePhabricator

Settle on and document Codex commit message guidelines
Closed, ResolvedPublic

Description

Codex is currently missing commit message guidelines. Specifically for faster orientation in Git log of a monorepo, we need to settle on and document those.

Previous convention
  • WVUI has been using [component||type] commit message subject, component or type in square brackets, several combined as [type0][type1]
  • WiKit hasn't had strict guidelines, but seemed to has at times followed a similar approach like Gerrit.
Outside Wikiverse

Body is mostly similar in conventions, footer needs to be Gerrit specific, focussing on subject:

  • Vue <type>(<scope>): <subject> Matched by following regular expression /^(revert: )?(feat|fix|polish|doc|style|refactor|perf|test|workflow|ci|chore|types)(\(.+\))?: .{1,50}/ and oriented on Angular below.
  • Angular: <type>(<scope>): <subject>, f.e. docs(changelog): update changelog to beta.5
Proposal

Orient on Gerrit commit guidelines:

  • Subject starting with component or type & ending with colon, in case of multiple type0, type1:, separated by , . Closer to natural language and simpler for other Wikimedia devs to orient on.
  • Special subject types are build, docs, styles, tests, types, possibly also themes, perf in future
  • Body & footer follows Gerrit guidance

Event Timeline

This sounds good to me generally.

One point of clarification: when you say component, you mean that as a placeholder for the name of the component affected, right? So example commit messages could look like:

  • Button: Fix styles for primary action
  • Checkbox: Toggle state when space bar is pressed
  • build: Update vue peerDependency to 3.2.20
  • docs: Add ADR for lint tools

And commits touching multiple things might look like:

  • Checkbox, ToggleSwitch: Add indeterminate state
  • design-tokens, docs: Automatically generate documentation for token structure

@Catrope That's right.

What do we think of the more detailed type with optional (scope) take of Vue.js?
To stay in @Catrope's examples:

  • fix(Button): Fix styles for primary action type
  • fix(Checkbox): Toggle state when space bar is pressed
  • build: Update Vue peerDependency to 3.2.20
  • docs: Add ADR for linting tools
  • `feat(Checkbox, ToggleSwitch): Add indeterminate state
  • docs(design-tokens): Generate documentation for token structure automatically

Types in our case: (feat|fix|polish|docs|styles|refactor|perf|test|build|types)
Differences: build instead of ci, styles for CSS only, do we need a style?, styles could actually sub-summed into others like polish, removed workflow(?)

Too much? Or worth a try?

I'd prefer to keep it simple and only require component or type

Refined for unifying to docs: and tests: plural over singular for those changes.

Updated Gerrit commit message guidelines with footer section.

Change 738477 had a related patch set uploaded (by VolkerE; author: VolkerE):

[design/codex@main] docs: Further clarify commit message guidelines

https://gerrit.wikimedia.org/r/738477

Change 738477 merged by jenkins-bot:

[design/codex@main] docs: Further clarify commit message guidelines

https://gerrit.wikimedia.org/r/738477

Volker_E claimed this task.