Source Code Management

Source Code Management

Commit Message Rules

All commits must have a proper commit message. Inspect the requested diff and git status --short, including staged and unstaged work, before describing it. Use the user's requested scope; do not include unrelated work merely because it is present in the checkout. Describe the final behavior and actual validation, not a transcript or an abandoned implementation. Creating a message does not stage files, create a commit, tag a release, or publish changes.

A hand-written commit message subject line must conform to the following rules:

• The first line of each commit message is the subject.
• The subject line MUST be less than 87 characters long.
• The subject line MUST NOT terminate with a period (.).
• The subject line MUST start with a change indicator followed by a colon (:).

Change Indicators

This repository uses change indicators as a mix of product-surface labels and maintenance labels. Prefer the most specific product surface when the change is clearly about one Caddy security directive, parser, provider, or runtime path. Use a maintenance label when the change is repository plumbing, documentation, testing, release work, or a bug fix that cuts across multiple surfaces.

Selection rules:

• Use exactly one indicator. Do not combine indicators or add parenthesized scopes.
• Prefer public Caddyfile and module names over internal abbreviations. For example, use authenticate instead of authn, and authorize instead of authz.
• Use caddyfile for parser/adaptation infrastructure that affects several directives, Caddyfile fixture changes, or generic config loading.
• Use provider indicators such as ldap, oauth, or saml only when the change is provider-specific. Use identity when the change is shared by identity stores or identity providers.
• Use breakfix for a reported regression, panic, or shipped behavior that is visibly broken for users. Use fix for narrower correctness fixes that are not tied to a known user breakage.
• Use tests, not unittest, for Go tests, Caddyfile adapt fixtures, and testdata changes whose primary purpose is coverage.
• Use skills for AI agent skills, skill metadata, or agent-facing repository instructions. Prefer it over docs or ops when the primary purpose is helping AI agents work with this repository.
• Use ops for dependency or toolchain version bumps. Use build only when the build behavior itself changes.
• The Makefile release target creates the subject ops: released v<VERSION>. For hand-written release workflow changes, use ops. Follow release-and-versioning for the release procedure and publication scope; an automated subject does not replace the body requirements for hand-written commit messages.
• Use various only when a commit intentionally spans unrelated surfaces and no more specific indicator is honest.
• Normalize older repository labels when creating new messages: use authenticate for authn, authorize for authz, ldap for ids/ldap, local for ids/local, feat for feature, and tests for unittest. Replace misc or chore with a more specific indicator when possible, or ops/various when it is truly general maintenance.
• Use colon form for new dependency bumps, such as ops: go-authcrunch to v1.1.40, even though older history has subjects like upgrade to github.com/greenpau/go-authcrunch v1.1.39.

Use one of these product-surface indicators:

• app: Caddy security app provisioning, lifecycle, config validation, or runtime config resolution
• authenticate: authenticate handler behavior, authentication portals, cookies, crypto, transforms, or authentication Caddyfile directives
• authorize: authorize handler behavior, authorization policies, ACLs, bypass rules, crypto, claim extraction, or header injection
• caddyfile: global security Caddyfile parsing, directive ordering, adapt behavior, parser helpers, or Caddyfile fixtures spanning multiple surfaces
• credentials: credential directives and credentials config
• identity: shared identity store or identity provider behavior
• ldap: LDAP-specific identity store or provider behavior
• local: local identity store or local user behavior
• messaging: messaging directives and messaging config
• oauth: OAuth or OpenID Connect provider behavior
• registration: user registration directives and registration policy behavior
• saml: SAML provider behavior
• secrets: secrets manager directives and secret resolution behavior
• sso: SSO provider directives and single sign-on provider config
• ui: portal UI directives, labels, icons, metadata, themes, or UI assets
• cmd: cmd/authcrunch wrapper behavior

Use one of these maintenance indicators:

• breakfix: reported regression, panic, or user-visible breakage fix
• fix: correctness fix without a known production breakage
• feat: user-facing capability that does not fit a more specific product surface indicator
• docs: documentation-only changes
• tests: test additions, fixture updates, or coverage improvements
• refactor: behavior-preserving code restructuring
• skills: AI agent skills, skill metadata, AGENTS.md, or agent-facing repository instructions
• ops: dependency, Caddy, Go, toolchain, release, version-reference, or repository maintenance changes
• build: Makefile, build output, xcaddy, packaging, or local build behavior
• github: GitHub Actions, issue templates, CLA workflow, or repository GitHub metadata
• security: vulnerability, dependency audit, hardening, or disclosure-policy changes
• various: intentionally mixed changes that do not fit one indicator