---
name: source-code-management
description: "Create or review caddy-security commit messages using repository indicators, required body sections, and timestamped message files. A message request does not create a commit."
---

# 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](../release-and-versioning/SKILL.md) 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

The commit message body must contain the following sections in this order:

1. `Before this commit:`
2. `After this commit:`
3. `Tests:`
4. `More info:`

The body may also contain the following optional sections:

1. `Resolves:`
2. `Partial Resolution:`
3. `See also:`
4. `Links:`

The following rules apply to the body of a commit message:

- Separate sections with one blank line.
- Each section title MUST end with a colon (`:`).
- Lines MUST NOT exceed 87 characters, except in `Links` and `More info`.
- Use `Resolves` ONLY when the PR or commit resolves an issue completely.
- Use `Partial Resolution` when the PR or commit addresses an issue partially.
- Use `See also` for additional related references.
- `Resolves`, `Partial Resolution`, and `See also` MUST contain valid links.
- Multiple links in those reference sections MUST be separated by comma and
  space (`, `).
- `Tests` MUST describe the command or manual check performed.
- If no smoke test was run, `Tests` MUST say `not run` and include the
  reason.
- `More info` MUST summarize the implementation details or notable decisions.

The `Links` section must contain a list of valid links or references, e.g.:

```text
  - Text reference
  - [HTTP link](http://google.com/)
```

Use this template for commit messages:

```text
indicator: concise subject under 87 characters

Before this commit: describe the previous behavior, limitation, or state.

After this commit: describe the new behavior, implementation, or state.

Tests: describe the command or manual check performed.

More info: summarize important implementation details or decisions.
```

For example, a commit message may look like this:

```text
docs: add contributing guidance

Before this commit: the repository had no guidance related to open-source
contributions.

After this commit: contribution guidance is documented in `CONTRIBUTING.md`.

Tests: reviewed the rendered Markdown manually.

More info: added a focused contributor workflow and repository etiquette notes.
```

## Commit Message File Workflow

For every request to create or generate a commit message, write it below
`tmp/commits` with a `YYYYMMDD_HHMM_` prefix and always provide the corresponding
`git commit -F ...` command. Do not require the user to ask separately for a
message file. A review-only request does not create a file unless asked.

Commit message files in `tmp/commits` are working artifacts and should not be
committed unless explicitly requested.

## Acceptance criteria

- The subject has one allowed indicator, is shorter than 87 characters, and has
  no final period. The required body sections appear in order and obey line limits.
- Tests names actual commands or manual checks performed and reports omitted
  smoke tests with their reason. A proposed test is never described as passing.
- A message request produces the timestamped file under `tmp/commits` and its
  `git commit -F` command; a review-only request does not create or commit files.