Contributor Commit And Changelog Rules

## Purpose

Use these rules when a contributor PR needs release-ready history. The goal is
not to force every tiny commit into ceremony. The goal is to make user-visible
changes, breaking changes, security fixes, migrations, and operator impact easy
to find when maintainers generate a release.

Clean commit and changelog discipline helps reviewers answer three questions:
what changed, who needs to know, and what release impact does it have?

## When A Changelog Entry Is Required

Require a changelog or release-note entry when the PR changes any public or
operator-visible behavior.

1. **User-visible behavior.** Features, fixes, UI text, CLI output, errors,
   docs-visible behavior, or changed defaults.
2. **Public contracts.** APIs, schemas, events, webhooks, file formats, config,
   environment variables, packages, or extension points.
3. **Breaking changes.** Removed behavior, renamed fields, incompatible
   migrations, changed auth, unsupported runtimes, or required manual steps.
4. **Security and privacy.** Vulnerability fixes, secret handling, logging,
   telemetry, permissions, data retention, or access-control changes.
5. **Operations.** Deployments, migrations, feature flags, monitoring,
   dependency updates, release automation, or rollback behavior.
6. **Deprecations.** Any behavior that remains available but has a planned
   removal path.

Do not require a changelog entry for purely internal refactors, tests, formatting
changes, or typo fixes unless they affect users, operators, integrators, or the
release process.

## Commit Message Rules

- Use the repository's documented style first; when none exists, prefer
  Conventional Commits for machine-readable history.
- Start the subject with a meaningful type such as `feat`, `fix`, `docs`,
  `perf`, `refactor`, `test`, `build`, `ci`, or `chore`.
- Add a scope when it helps reviewers identify the subsystem, package, or
  public surface.
- Keep the subject specific enough to explain behavior, not just activity.
- Use `!` after the type or scope for breaking changes, and add a
  `BREAKING CHANGE:` footer with migration details.
- Put issue closure keywords in the PR body when the project wants linked
  issues closed on merge.
- Avoid mixing unrelated changes under one broad message; split commits or PRs
  when the release impact differs.
- Do not include secrets, customer names, private URLs, raw logs, exploit
  details, or internal incident notes in commit text.

For squash-merge repositories, the final PR title and squash body matter more
than every intermediate commit. Review the merge commit text before approval.

## Changelog Rules

Use the repository's changelog format first. When a project follows Keep a
Changelog, place unreleased entries under categories such as Added, Changed,
Deprecated, Removed, Fixed, and Security.

- Write entries for readers, not only maintainers.
- Name the user, operator, API, security, or migration impact.
- Include issue or PR references only when they help traceability.
- Keep internal implementation details out of public notes unless they affect
  users.
- Mark breaking changes and required manual actions near the entry, not hidden
  in a commit body.
- Do not duplicate the same change across multiple categories.
- Keep unreleased entries concise enough to survive into release notes.
- Remove speculative or future-tense notes that are not part of the PR.

If the project generates release notes from commits, compare the generated
preview with the hand-written changelog before merge.

## SemVer Impact Rules

Map the PR's release impact before approving release-note text.

- Patch: backward-compatible bug fix, documentation correction, internal test
  improvement, or safe dependency/security patch.
- Minor: backward-compatible feature, new option, new API field, new command, or
  deprecation notice.
- Major: incompatible API, config, runtime, data, CLI, auth, schema, migration,
  or behavior change.

When the impact is uncertain, make the uncertainty explicit in the PR. Do not
let ambiguous commit messages choose the version bump silently.

## Merge Blockers

Block merge until resolved when:

- the PR title or squash commit is too vague for release history;
- a breaking change lacks a `!` marker or `BREAKING CHANGE:` footer;
- a user-visible change has no changelog or release-note evidence;
- the changelog entry promises behavior that the diff does not implement;
- the SemVer impact is missing for public API, config, schema, runtime, or CLI
  changes;
- issue links, closure keywords, or migration notes point to the wrong work;
- generated release notes include private names, raw logs, branch names,
  incident details, or vulnerability exploit context;
- unrelated changes with different release impact are bundled into one commit
  or one changelog entry.

## Review Checklist

- [ ] {"task": "Style follows project policy", "description": "Commit title, PR title, or squash message follows the repository's documented convention"}
- [ ] {"task": "Change type is clear", "description": "The message explains whether the PR is a feature, fix, docs update, build change, CI change, refactor, or chore"}
- [ ] {"task": "Changelog need decided", "description": "The reviewer decided whether the PR needs an Unreleased changelog or release-note entry"}
- [ ] {"task": "Breaking changes marked", "description": "Any incompatible behavior has a visible marker, migration note, and SemVer impact"}
- [ ] {"task": "Issue links correct", "description": "Linked issues and closure keywords point to the intended work"}
- [ ] {"task": "Privacy safe", "description": "Commit text, changelog notes, and generated release notes avoid private data and sensitive security details"}

## Troubleshooting

- **The contributor used vague commits:** use a squash commit or ask for a
  history cleanup before merge.
- **The changelog entry is too technical:** rewrite it around the user,
  operator, API, or security impact.
- **A release tool generated noisy notes:** fix the commit type, scope, or body
  before merging instead of editing only the generated output later.
- **The PR has both breaking and non-breaking work:** split it or clearly mark
  the major-version impact.
- **Security details are sensitive:** use public-safe wording and move exploit
  details to the approved private advisory process.

## Duplicate And History Check

Checked existing rules, guides, hooks, commands, skills, open PRs, and closed
PR history for commit message rules, changelog rules, Conventional Commits,
Keep a Changelog, SemVer release notes, git commit generators, changelog
commands, pre-commit validators, and release automation skills.

Adjacent content includes the release-notes drafting command, git-smart-commit
command, git pre-commit validator hook, git-cliff changelog skill, and
documentation freshness rules. This entry is distinct because it is a portable
review policy for contributor PRs: it tells reviewers when commit text,
changelog entries, linked issues, breaking-change markers, SemVer impact, and
privacy-safe release notes are required before merge.

The earlier PR for this slot was closed after public content validation failed.
This submission uses the current rules schema, includes practical safety and
privacy notes, and adds exactly one source rules file.

## Sources

- Conventional Commits 1.0.0 - https://www.conventionalcommits.org/en/v1.0.0/
- Keep a Changelog 1.1.0 - https://keepachangelog.com/en/1.1.0/
- Semantic Versioning 2.0.0 - https://semver.org/spec/v2.0.0.html
- GitHub Docs: Linking a pull request to an issue - https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue
- GitHub Docs: About releases - https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases