| name | change-notes |
| description | Use this skill whenever writing or reviewing commit messages, pull request descriptions, release notes, GitHub Releases, or changelog entries. The goal is to produce clear, human-readable change descriptions that explain what changed, why it matters, who is affected, and whether any action is required. Do not use this skill for code implementation unless the task includes change documentation. |
Human-Readable Change Notes Skill
Write change descriptions that can be understood by both developers and non-technical users.
Every commit, pull request, release note, and changelog entry should explain the change well enough to support future changelog writing.
Do not write vague entries like:
- fixed stuff
- update files
- misc cleanup
- improve UI
- bug fixes
Instead, explain the change in plain language.
Core rule
For every meaningful change, capture:
- What changed
- Why it changed
- Who is affected
- What the user or operator will notice
- Whether any action is required
- Whether there is risk, migration, rollback, or compatibility impact
Use short, direct sentences.
Prefer:
Fixed a bug where duplicate NFC scans could create duplicate attendance records.
Avoid:
Fix NFC issue.
Commit Messages
Commit messages should explain one focused change. A good commit message helps a future maintainer understand why the change exists without opening every file.
Use this format:
<type>: <plain-language summary>
<what changed>
<why it changed>
<impact or risk, if any>
Use one of these Conventional Commit types:
- feat: New user-visible capability
- fix: Bug fix
- docs: Documentation-only change
- refactor: Internal restructuring with no intended behavior change
- test: Test changes
- chore: Maintenance, dependency, config, or tooling change
- ci: Continuous integration or automation workflow change
- build: Build system, packaging, or dependency pipeline change
- perf: Performance improvement
- security: Security-related change
- deploy: Installer, updater, release, Docker, CI/CD, or appliance deployment change
- db: Database schema, migration, seed, or Prisma-related change
- ux: User experience or interface clarity change
Before finalizing a commit message, ensure it answers:
- What changed?
- Why was it needed?
- Is this user-visible?
- Is this operator-visible?
- Does it affect deployment, update, rollback, backup, restore, database, authentication, permissions, or configuration?
- Does it require follow-up work?
Use concise examples:
fix: prevent duplicate attendance records from repeated NFC scans
Adds a server-side duplicate check before creating an attendance record.
This prevents accidental double entries when a member taps their NFC tag more than once.
No database migration is required.
deploy: reject unsafe latest image tags during updates
Updates the appliance updater to require an explicit vX.Y.Z version.
This prevents accidental deployment of untested images.
Operators must provide a version when running update.sh.
Avoid:
fix: bug
update updater
Pull Request Descriptions
A PR description should explain the complete change set in a way that supports review, testing, release notes, and future changelog writing.
Use this template:
## Summary
- Explain the change in 2-5 plain-language bullets.
## Why this change was needed
Explain the problem, gap, risk, or user need.
## What changed
### User-facing
- Include only if applicable.
### Admin/operator-facing
- Include only if applicable.
### Backend/API
- Include only if applicable.
### Database
- Include only if applicable.
### Deployment/update
- Include only if applicable.
### Documentation
- Include only if applicable.
### Tests
- Include only if applicable.
## User impact
Explain what a normal user will notice.
## Operator impact
Explain what an admin, maintainer, or installer operator will notice.
## Upgrade or migration notes
State one of:
- No upgrade action required.
- Database migration required.
- Configuration change required.
- Manual operator action required.
Include exact commands when known.
## Risk and rollback notes
Explain:
- Main risk
- How to verify the change
- Whether rollback is safe
- Any data compatibility concerns
## Testing performed
List actual checks run.
## Changelog candidates
Write human-readable bullets suitable for the release changelog.
When a fuller PR example would help, read references/examples.md.
PR writing rules:
- Write for a Staff Officer, department user, or appliance operator, not just another developer.
- Explain acronyms the first time unless they are already common in the project.
- Mention database migrations clearly.
- Mention config/env changes clearly.
- Mention breaking changes clearly.
- Mention security-sensitive changes clearly.
- Mention changes to install.sh, update.sh, rollback.sh, backup.sh, restore.sh, Docker, Caddy, GitHub Actions, or GHCR images clearly.
- Do not bury operational risks in technical details.
Release Notes / GitHub Release Descriptions
Release notes should be readable by non-technical users and useful for operators performing upgrades. They should not be raw commit dumps.
Use this template:
# Sentinel vX.Y.Z
## Plain-language summary
Briefly explain what this release does and why it matters.
## Highlights
- Important user-facing change
- Important operator-facing change
- Important fix or safety improvement
## Added
New features or capabilities.
## Changed
Behavior changes, UX changes, deployment changes, or process changes.
## Fixed
Bug fixes.
## Security
Security fixes, dependency vulnerability fixes, permission changes, authentication changes, or safer defaults.
## Deployment and upgrade notes
Include:
- Required version
- Required commands
- Database migration status
- Config/env changes
- Docker/GHCR image notes
- Service restart expectations
## Breaking changes
State `None` if there are no breaking changes.
## Known issues
State `None known` if there are no known issues.
## Rollback notes
Explain whether rollback is safe and include the rollback method if known.
## Verification checklist
List the practical checks an operator should complete after updating.
When a fuller release example would help, read references/examples.md.
Release note rules:
- Put the most important information first.
- Separate user-facing changes from operator/deployment changes.
- State clearly whether a database migration is required.
- State clearly whether configuration changes are required.
- State clearly whether rollback is safe.
- Use exact version numbers.
- Avoid developer-only wording unless it is in the technical/operator section.
- Do not include every commit. Summarize meaningful changes.
Changelog Entry Standards
Use changelog categories inspired by Keep a Changelog:
- Added
- Changed
- Deprecated
- Removed
- Fixed
- Security
For Sentinel, also use these operational sections when relevant:
- Deployment
- Database
- Upgrade Notes
- Rollback Notes
- Known Issues
Each changelog bullet should follow this pattern:
- <Plain-language change>. <Why it matters or who it affects.>
Examples:
### Fixed
- Fixed duplicate attendance records from repeated NFC scans. This prevents accidental double-counting when a member taps their tag more than once.
### Deployment
- Added explicit version validation to the updater. Operators must now provide a version such as `v1.2.0`.
### Upgrade Notes
- No database migration is required.
Required review before final output
Before producing a commit message, PR description, release note, or changelog entry, review it against this checklist:
- Is it understandable to a non-technical reader?
- Does it explain why the change matters?
- Does it identify user impact?
- Does it identify operator impact?
- Does it mention deployment/update impact if relevant?
- Does it mention database migration impact if relevant?
- Does it mention config/env changes if relevant?
- Does it mention security impact if relevant?
- Does it mention breaking changes if relevant?
- Does it avoid vague wording?
- Could this be copied into a changelog with minimal editing?
If any answer is missing, revise before finalizing.
Output preference
When asked to write a commit message, PR description, release note, or changelog entry:
- Produce the finished text first.
- Then provide a short "Why this works" note only if helpful.
- Do not over-explain unless asked.
