Guideline Workflow

Purpose: Creation, updating, and automation of coding guidelines

Audience: Developers, Reviewers, Maintainers

Status: Draft

Rationale

Guidelines should document how we want to write code. When a guideline can be checked reliably by tooling, it should be automated instead of relying on manual review.

This keeps guidelines readable and makes objective checks repeatable.

Workflow Steps

Step 1. Define Guideline

Who: Person who sees the need for a guideline
When: A coding pattern should be documented or changed
Actions:

  • create an issue using the enhancement template
  • describe:
    • Use Case: why the guideline is needed
    • Description: what should be added or changed

Step 2. Document Guideline

Who: Person assigned to the issue
When: During an iteration
Actions:

  • create an MR that updates the relevant guideline document
  • describe the guideline manually
  • keep it short
  • add examples when needed

Step 3. Automate Guideline

Who: Person assigned to the follow-up issue
When: When the guideline can be checked reliably by tooling
Actions:

  • create a follow-up issue if automation is useful
  • implement the check with tools such as ESLint, Prettier, TypeScript, pre-commit, CI, or tests
  • update existing code if needed
  • make sure the check runs locally and/or in CI
  • simplify the guideline document once the rule is enforced automatically:
    • reduce manual wording
    • link to the relevant tool configuration
    • keep only the intention of the rule and how it is enforced

Notes

Not every guideline should be automated. Only automate rules that can be checked objectively and reliably.