You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
335 lines
10 KiB
335 lines
10 KiB
---
|
|
description: interacting with git
|
|
alwaysApply: false
|
|
---
|
|
# Directive: Peaceful Co-Existence with Developers
|
|
|
|
**Author**: Matthew Raymer
|
|
**Date**: 2025-08-19
|
|
**Status**: 🎯 **ACTIVE** - Version control guidelines
|
|
|
|
## 1) Version-Control Ownership
|
|
|
|
- **MUST NOT** run `git add`, `git commit`, or any write action.
|
|
- **MUST** leave staging/committing to the developer.
|
|
|
|
## 2) Source of Truth for Commit Text
|
|
|
|
- **MUST** derive messages **only** from:
|
|
- files **staged** for commit (primary), and
|
|
- files **awaiting staging** (context).
|
|
- **MUST** use the **diffs** to inform content.
|
|
- **MUST NOT** invent changes or imply work not present in diffs.
|
|
|
|
## 3) Mandatory Preview Flow
|
|
|
|
- **ALWAYS** present, before any real commit:
|
|
- file list + brief per-file notes,
|
|
- a **draft commit message** (copy-paste ready),
|
|
- nothing auto-applied.
|
|
|
|
## 4) Version Synchronization Requirements
|
|
|
|
- **MUST** check for version changes in `package.json` before committing
|
|
- **MUST** ensure `CHANGELOG.md` is updated when `package.json` version
|
|
changes
|
|
- **MUST** validate version format consistency between both files
|
|
- **MUST** include version bump commits in changelog with proper semantic
|
|
versioning
|
|
|
|
### Version Sync Checklist (Before Commit)
|
|
|
|
- [ ] `package.json` version matches latest `CHANGELOG.md` entry
|
|
- [ ] New version follows semantic versioning
|
|
(MAJOR.MINOR.PATCH[-PRERELEASE])
|
|
- [ ] Changelog entry includes all significant changes since last version
|
|
- [ ] Version bump commit message follows `build(version): bump to X.Y.Z`
|
|
format
|
|
- [ ] Breaking changes properly documented with migration notes
|
|
- [ ] Alert developer in chat message that version has been updated
|
|
|
|
### Version Change Detection
|
|
|
|
- **Check for version changes** in staged/unstaged `package.json`
|
|
- **Alert developer** if version changed but changelog not updated
|
|
- **Suggest changelog update** with proper format and content
|
|
- **Validate semantic versioning** compliance
|
|
|
|
### Implementation Notes
|
|
|
|
- **Version Detection**: Compare `package.json` version field with latest
|
|
changelog entry
|
|
- **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]`
|
|
format
|
|
- **Changelog Format**: Follow [Keep a Changelog](https://keepachangelog.com/)
|
|
standards
|
|
- **Breaking Changes**: Use `!` in commit message and `BREAKING CHANGE:`
|
|
in changelog
|
|
- **Pre-release Versions**: Include beta/alpha/rc suffixes in both files
|
|
consistently
|
|
|
|
## Commit Message Format (Normative)
|
|
|
|
### A. Subject Line (required)
|
|
|
|
```
|
|
<type>(<scope>)<!>: <summary>
|
|
```
|
|
|
|
- **type** (lowercase, Conventional Commits):
|
|
`feat|fix|refactor|perf|docs|test|build|chore|ci|revert`
|
|
- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`)
|
|
- **!**: include when a breaking change is introduced
|
|
- **summary**: imperative mood, ≤ 72 chars, no trailing period
|
|
|
|
**Examples**
|
|
|
|
- `fix(api): handle null token in refresh path`
|
|
- `feat(ui/login)!: require OTP after 3 failed attempts`
|
|
|
|
### B. Body (optional, when it adds non-obvious value)
|
|
|
|
- One blank line after subject.
|
|
- Wrap at ~72 chars.
|
|
- Explain **what** and **why**, not line-by-line "how".
|
|
- Include brief notes like tests passing or TS/lint issues resolved
|
|
**only if material**.
|
|
|
|
**Body checklist**
|
|
|
|
- [ ] Problem/symptom being addressed
|
|
- [ ] High-level approach or rationale
|
|
- [ ] Risks, tradeoffs, or follow-ups (if any)
|
|
|
|
### C. Footer (optional)
|
|
|
|
- Issue refs: `Closes #123`, `Refs #456`
|
|
- Breaking change (alternative to `!`):
|
|
`BREAKING CHANGE: <impact + migration note>`
|
|
- Authors: `Co-authored-by: Name <email>`
|
|
- Security: `CVE-XXXX-YYYY: <short note>` (if applicable)
|
|
|
|
## Content Guidance
|
|
|
|
### Include (when relevant)
|
|
|
|
- Specific fixes/features delivered
|
|
- Symptoms/problems fixed
|
|
- Brief note that tests passed or TS/lint errors resolved
|
|
|
|
### Avoid
|
|
|
|
- Vague: *improved, enhanced, better*
|
|
- Trivialities: tiny docs, one-liners, pure lint cleanups (separate,
|
|
focused commits if needed)
|
|
- Redundancy: generic blurbs repeated across files
|
|
- Multi-purpose dumps: keep commits **narrow and focused**
|
|
- Long explanations that good inline code comments already cover
|
|
|
|
**Guiding Principle:** Let code and inline docs speak. Use commits to
|
|
highlight what isn't obvious.
|
|
|
|
## Copy-Paste Templates
|
|
|
|
### Minimal (no body)
|
|
|
|
```text
|
|
<type>(<scope>): <summary>
|
|
```
|
|
|
|
### Standard (with body & footer)
|
|
|
|
```text
|
|
<type>(<scope>)<!>: <summary>
|
|
|
|
<why-this-change?>
|
|
<what-it-does?>
|
|
<risks-or-follow-ups?>
|
|
|
|
Closes #<id>
|
|
BREAKING CHANGE: <impact + migration>
|
|
Co-authored-by: <Name> <email>
|
|
```
|
|
|
|
## Assistant Output Checklist (before showing the draft)
|
|
|
|
- [ ] List changed files + 1–2 line notes per file
|
|
- [ ] Provide **one** focused draft message (subject/body/footer)
|
|
- [ ] Subject ≤ 72 chars, imperative mood, correct `type(scope)!` syntax
|
|
- [ ] Body only if it adds non-obvious value
|
|
- [ ] No invented changes; aligns strictly with diffs
|
|
- [ ] Render as a single copy-paste block for the developer
|
|
|
|
---
|
|
|
|
**Status**: Active version control guidelines
|
|
**Priority**: High
|
|
**Estimated Effort**: Ongoing reference
|
|
**Dependencies**: git, package.json, CHANGELOG.md
|
|
**Stakeholders**: Development team, AI assistants
|
|
|
|
- [ ] No invented changes; aligns strictly with diffs
|
|
- [ ] Render as a single copy-paste block for the developer
|
|
|
|
## 1) Version-Control Ownership
|
|
|
|
- **MUST NOT** run `git add`, `git commit`, or any write action.
|
|
- **MUST** leave staging/committing to the developer.
|
|
|
|
## 2) Source of Truth for Commit Text
|
|
|
|
- **MUST** derive messages **only** from:
|
|
- files **staged** for commit (primary), and
|
|
- files **awaiting staging** (context).
|
|
- **MUST** use the **diffs** to inform content.
|
|
- **MUST NOT** invent changes or imply work not present in diffs.
|
|
|
|
## 3) Mandatory Preview Flow
|
|
|
|
- **ALWAYS** present, before any real commit:
|
|
- file list + brief per-file notes,
|
|
- a **draft commit message** (copy-paste ready),
|
|
- nothing auto-applied.
|
|
|
|
## 4) Version Synchronization Requirements
|
|
|
|
- **MUST** check for version changes in `package.json` before committing
|
|
- **MUST** ensure `CHANGELOG.md` is updated when `package.json` version
|
|
changes
|
|
- **MUST** validate version format consistency between both files
|
|
- **MUST** include version bump commits in changelog with proper semantic
|
|
versioning
|
|
|
|
### Version Sync Checklist (Before Commit)
|
|
|
|
- [ ] `package.json` version matches latest `CHANGELOG.md` entry
|
|
- [ ] New version follows semantic versioning
|
|
(MAJOR.MINOR.PATCH[-PRERELEASE])
|
|
- [ ] Changelog entry includes all significant changes since last version
|
|
- [ ] Version bump commit message follows `build(version): bump to X.Y.Z`
|
|
format
|
|
- [ ] Breaking changes properly documented with migration notes
|
|
- [ ] Alert developer in chat message that version has been updated
|
|
|
|
### Version Change Detection
|
|
|
|
- **Check for version changes** in staged/unstaged `package.json`
|
|
- **Alert developer** if version changed but changelog not updated
|
|
- **Suggest changelog update** with proper format and content
|
|
- **Validate semantic versioning** compliance
|
|
|
|
### Implementation Notes
|
|
|
|
- **Version Detection**: Compare `package.json` version field with latest
|
|
changelog entry
|
|
- **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]`
|
|
format
|
|
- **Changelog Format**: Follow [Keep a Changelog](https://keepachangelog.com/)
|
|
standards
|
|
- **Breaking Changes**: Use `!` in commit message and `BREAKING CHANGE:`
|
|
in changelog
|
|
- **Pre-release Versions**: Include beta/alpha/rc suffixes in both files
|
|
consistently
|
|
|
|
## Commit Message Format (Normative)
|
|
|
|
### A. Subject Line (required)
|
|
|
|
```
|
|
<type>(<scope>)<!>: <summary>
|
|
```
|
|
|
|
- **type** (lowercase, Conventional Commits):
|
|
`feat|fix|refactor|perf|docs|test|build|chore|ci|revert`
|
|
- **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`)
|
|
- **!**: include when a breaking change is introduced
|
|
- **summary**: imperative mood, ≤ 72 chars, no trailing period
|
|
|
|
**Examples**
|
|
|
|
- `fix(api): handle null token in refresh path`
|
|
- `feat(ui/login)!: require OTP after 3 failed attempts`
|
|
|
|
### B. Body (optional, when it adds non-obvious value)
|
|
|
|
- One blank line after subject.
|
|
- Wrap at ~72 chars.
|
|
- Explain **what** and **why**, not line-by-line "how".
|
|
- Include brief notes like tests passing or TS/lint issues resolved
|
|
**only if material**.
|
|
|
|
**Body checklist**
|
|
|
|
- [ ] Problem/symptom being addressed
|
|
- [ ] High-level approach or rationale
|
|
- [ ] Risks, tradeoffs, or follow-ups (if any)
|
|
|
|
### C. Footer (optional)
|
|
|
|
- Issue refs: `Closes #123`, `Refs #456`
|
|
- Breaking change (alternative to `!`):
|
|
`BREAKING CHANGE: <impact + migration note>`
|
|
- Authors: `Co-authored-by: Name <email>`
|
|
- Security: `CVE-XXXX-YYYY: <short note>` (if applicable)
|
|
|
|
## Content Guidance
|
|
|
|
### Include (when relevant)
|
|
|
|
- Specific fixes/features delivered
|
|
- Symptoms/problems fixed
|
|
- Brief note that tests passed or TS/lint errors resolved
|
|
|
|
### Avoid
|
|
|
|
- Vague: *improved, enhanced, better*
|
|
- Trivialities: tiny docs, one-liners, pure lint cleanups (separate,
|
|
focused commits if needed)
|
|
- Redundancy: generic blurbs repeated across files
|
|
- Multi-purpose dumps: keep commits **narrow and focused**
|
|
- Long explanations that good inline code comments already cover
|
|
|
|
**Guiding Principle:** Let code and inline docs speak. Use commits to
|
|
highlight what isn't obvious.
|
|
|
|
## Copy-Paste Templates
|
|
|
|
### Minimal (no body)
|
|
|
|
```text
|
|
<type>(<scope>): <summary>
|
|
```
|
|
|
|
### Standard (with body & footer)
|
|
|
|
```text
|
|
<type>(<scope>)<!>: <summary>
|
|
|
|
<why-this-change?>
|
|
<what-it-does?>
|
|
<risks-or-follow-ups?>
|
|
|
|
Closes #<id>
|
|
BREAKING CHANGE: <impact + migration>
|
|
Co-authored-by: <Name> <email>
|
|
```
|
|
|
|
## Assistant Output Checklist (before showing the draft)
|
|
|
|
- [ ] List changed files + 1–2 line notes per file
|
|
- [ ] Provide **one** focused draft message (subject/body/footer)
|
|
- [ ] Subject ≤ 72 chars, imperative mood, correct `type(scope)!` syntax
|
|
- [ ] Body only if it adds non-obvious value
|
|
- [ ] No invented changes; aligns strictly with diffs
|
|
- [ ] Render as a single copy-paste block for the developer
|
|
|
|
---
|
|
|
|
**Status**: Active version control guidelines
|
|
**Priority**: High
|
|
**Estimated Effort**: Ongoing reference
|
|
**Dependencies**: git, package.json, CHANGELOG.md
|
|
**Stakeholders**: Development team, AI assistants
|
|
|
|
* [ ] No invented changes; aligns strictly with diffs
|
|
* [ ] Render as a single copy-paste block for the developer
|
|
|