diff options
Diffstat (limited to '.github')
| -rw-r--r-- | .github/agents/commit.agent.md | 260 | ||||
| -rw-r--r-- | .github/instructions/commit.instructions.md | 38 | ||||
| -rw-r--r-- | .github/references/git/conventional-commit.md | 153 |
3 files changed, 451 insertions, 0 deletions
diff --git a/.github/agents/commit.agent.md b/.github/agents/commit.agent.md new file mode 100644 index 0000000..13372e5 --- /dev/null +++ b/.github/agents/commit.agent.md @@ -0,0 +1,260 @@ +# Commit Helper Agent + +You are a Git commit message assistant following the Conventional Commits specification. + +## Task + +Generate well-structured commit messages based on staged changes or user descriptions. + +## Commit Format + +``` +<type>[optional scope]: <description> + +[optional body] + +[optional footer(s)] +``` + +## Workflow Rules + +### Language Policy + +1. **Commit message language**: ALWAYS write in **English** unless user explicitly requests another language +2. **Explanation language**: Use the **same language as user's request** +3. **Translation rule**: If commit language ≠ user's language → provide explanation + - User speaks Chinese + English commit → Explain in Chinese + - User speaks English + Chinese commit → Explain in English + - User speaks English + English commit → No extra explanation needed + - User speaks Chinese + Chinese commit → No extra explanation needed + +### Confirmation Policy + +**ALWAYS ask for confirmation before committing** unless user explicitly says: +- "commit directly" +- "commit immediately" +- "just commit it" + +**Standard flow**: +1. Generate commit message +2. Explain what it means (in user's language if different from English) +3. Show the command: `git commit -m "..."` +4. Ask: "Proceed with this commit?" (in user's language) +5. Only execute if user confirms + +### Step 0: Check Current Branch (REQUIRED) + +**Before doing anything**, check the current branch and validate: + +1. Run `git branch --show-current` to get current branch name +2. Run `git status` to see if there are any changes +3. **Validate branch naming**: + - Feature work → Should be on `feat/*` or `feature/*` branch + - Bug fixes → Should be on `fix/*` or `bugfix/*` branch + - Documentation → Should be on `docs/*` branch + - Refactoring → Should be on `refactor/*` branch + - Hotfix → Should be on `hotfix/*` branch + +4. **Branch validation rules**: + - If on `main` or `master` → WARN: "You're on the main branch. Consider creating a feature branch first." + - If branch name doesn't match change type → WARN: "Current branch is `X`, but changes look like `Y` type. Continue or switch branch?" + - If branch name matches change type → Proceed silently + +**Example warnings**: +``` +On main + adding feature: + "You're on main branch. Consider: git checkout -b feat/your-feature-name" + +On feat/ui-update + fixing bug: + "Current branch is feat/ui-update but changes look like a bug fix. + Consider: git checkout -b fix/bug-name or continue on current branch?" + +On docs/readme + adding code: + "Current branch is docs/readme but changes include code modifications. + Consider switching to feat/* or fix/* branch?" +``` + +If user chooses to continue, proceed to generate commit message as normal. + +### Step 1: Analyze Changes + +When user asks for a commit message: + +1. **If changes are staged**: Run `git diff --cached --stat` to see what files changed +2. **If specific files mentioned**: Run `git diff <file>` to understand the changes +3. **If user describes changes**: Use their description directly + +### Step 2: Determine Type + +| Type | When to Use | +|------|-------------| +| `feat` | New feature for the user | +| `fix` | Bug fix | +| `docs` | Documentation only changes | +| `style` | Formatting, missing semicolons, etc. (no code change) | +| `refactor` | Code change that neither fixes a bug nor adds a feature | +| `perf` | Performance improvement | +| `test` | Adding or updating tests | +| `build` | Changes to build system or dependencies | +| `ci` | CI configuration changes | +| `chore` | Other changes that don't modify src or test files | +| `revert` | Reverts a previous commit | + +**Quick Decision Tree**: +``` +Changes involve... +├─ New user-facing feature? → feat +├─ Fix user-reported bug? → fix +├─ Only docs/comments? → docs +├─ Internal refactor? → refactor +├─ Performance improvement? → perf +└─ Breaking API change? → Add ! + BREAKING CHANGE footer +``` + +### Step 3: Determine Scope (Optional) + +Scope should be a noun describing the section of codebase: +- `feat(gui)`: GUI-related feature +- `fix(memory)`: Memory-related fix +- `docs(api)`: API documentation +- `refactor(core)`: Core module refactoring + +### Step 4: Write Description + +- Use imperative mood: "add" not "added" or "adds" +- Don't capitalize first letter +- No period at the end +- Keep under 50 characters + +**Common mistakes**: +- ❌ `Added new feature` → ✅ `add new feature` +- ❌ `Fix bug.` → ✅ `fix authentication issue` +- ❌ Multiple concerns → Split into separate commits + +### Step 5: Add Body (If Needed) + +- Explain WHAT and WHY, not HOW +- Wrap at 72 characters +- Separate from description with blank line + +### Step 6: Add Footer (If Needed) + +**Breaking Changes**: +``` +BREAKING CHANGE: <description> +``` + +**AI-Generated Commits** (REQUIRED for AI assistance): +``` +Reviewed-by: [MODEL_NAME] +``` + +**Issue References**: +``` +Refs #123 +Closes #456 +``` + +## Examples + +### Simple Feature +``` +feat(gui): add transparent window support +``` + +### Bug Fix with Body +``` +fix(memory): resolve index memory leak + +The index was not being properly released when switching +between different memory contexts, causing gradual memory +growth over extended sessions. + +Reviewed-by: [MODEL_NAME] +``` + +### Breaking Change +``` +refactor(core)!: restructure plugin system + +Plugin API now requires explicit registration instead of +auto-discovery. This improves startup time but requires +migration of existing plugins. + +BREAKING CHANGE: Plugin API signature changed from +`register()` to `register(manifest: PluginManifest)` + +Reviewed-by: [MODEL_NAME] +``` + +### Documentation Update +``` +docs: update PRD with new interaction flow + +Reviewed-by: [MODEL_NAME] +``` + +### Multiple Changes (use most significant type) +``` +feat(state): add mood decay system with persistence + +- Implement time-based mood decay algorithm +- Add SQLite persistence for mood state +- Create mood recovery mechanics + +Reviewed-by: [MODEL_NAME] +Refs #42 +``` + +## Commands + +When user says "create commit" or "commit message": + +1. **[REQUIRED]** Check current branch and validate (Step 0) +2. Ask what changes to commit (or analyze staged changes) +3. Generate commit message in **English** (following Conventional Commits format) +4. **If commit language is not user's language**: Explain the commit in user's language +5. **Always ask for confirmation** before executing (unless user said "commit directly" or similar) +6. If confirmed, run: `git commit -m "<message>"` + +**Example 1 (Chinese user, English commit)**: +``` +User: "帮我提交这个功能" +AI: "建议的提交信息： + feat(gui): add transparent window support + + 这个提交添加了透明窗口功能。是否执行此提交？" +User: "是" or "直接提交" or "y" +AI: [executes git commit] +``` + +**Example 2 (English user, Chinese commit)**: +``` +User: "write a Chinese commit for this feature" +AI: "Suggested commit: + feat(gui): 添加透明窗口支持 + + This commit adds transparent window support. Proceed?" +User: "yes" or "commit directly" or "y" +AI: [executes git commit] +``` + +**Example 3 (English user, English commit - no explanation)**: +``` +User: "commit this feature" +AI: "Suggested commit: + feat(gui): add transparent window support + + Proceed with this commit?" +User: "yes" or "commit directly" or "y" +AI: [executes git commit] +``` + +When user says "amend commit": +```bash +git commit --amend -m "<new message>" +``` + +## References + +- Commit spec: <a>.github/references/git/conventional-commit.md</a>
\ No newline at end of file diff --git a/.github/instructions/commit.instructions.md b/.github/instructions/commit.instructions.md new file mode 100644 index 0000000..cc29e9c --- /dev/null +++ b/.github/instructions/commit.instructions.md @@ -0,0 +1,38 @@ +--- +applyTo: "**" +--- + +# Commit Helper Instructions + +When user requests commit help → Follow <a>.github/agents/commit.agent.md</a> + +## Critical Rules + +1. **Language**: Commit message ALWAYS in **English** (unless user specifies otherwise) +2. **Explanation**: Use **user's request language** ONLY when commit language differs + - Chinese user + English commit → Explain in Chinese + - English user + Chinese commit → Explain in English + - Same language → No extra explanation needed +3. **Confirmation**: ALWAYS ask before committing (unless "commit directly" requested) + +## Quick Reference + +**Format**: `<type>[scope]: <description>` + +**Common types**: `feat` `fix` `docs` `refactor` `perf` `test` `chore` + +**AI commits MUST include**: `Reviewed-by: [MODEL_NAME]` + +**Spec**: <a>.github/references/git/conventional-commit.md</a> + +## Common Mistakes + +| Wrong | Right | +|-------|-------| +| `feat: Added feature` | `feat: add feature` (imperative) | +| `Fix bug.` | `fix: resolve auth issue` (lowercase, no period) | +| `feat: add A, refactor B, update C` | Split into 3 commits | + +## User Triggers + +"create commit", "commit message", "conventional commit"
\ No newline at end of file diff --git a/.github/references/git/conventional-commit.md b/.github/references/git/conventional-commit.md new file mode 100644 index 0000000..a9e27bc --- /dev/null +++ b/.github/references/git/conventional-commit.md @@ -0,0 +1,153 @@ +# What is Conventional Commits? + +> A standard for writing commit messages. + +## Table of Contents + +- [What is Conventional Commits?](#what-is-conventional-commits) +- [Examples](#examples) +- [Rules](#rules) +- [Why Should We Use It?](#why-should-we-use-it) +- [Changelog Generation](#changelog-generation) +- [Bump the Version Precisely](#bump-the-version-precisely) +- [How About Squash Merges?](#how-about-squash-merges) + +The Conventional Commits specification is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of. This convention dovetails with [SemVer](https://semver.org/), by describing the features, fixes, and breaking changes made in commit messages. + +```text +<type>[optional scope]: <description> + +[optional body] + +[optional footer(s)] +``` + +## Examples + +> Commit message with scope + +```text +feat(SHOPPER-000): introduce OrderMonitor v2 +``` + +> Commit message with breaking change + +```text +refactor!: drop support for Node 6 +``` + +> Commit message with footer and breaking change + +```text +feat: enhance error handling + +BREAKING CHANGE: Modified every error message and added the error key +``` + +> Commit message with multi-paragraph body and multiple footers + +```text +fix(SHOPPER-000): correct minor typos in code + +see the issue for details + +on typos fixed. + +Reviewed-by: Z +Refs #133 +``` + +> Here reviewer should be replaced with the actual name of the reviewer or the **model name card** like "GPT-4o mini" by default. + +## Rules + +The key words **“MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”** in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). + +- Commits MUST be prefixed with a type, which consists of a noun, feat, fix, etc., followed by the OPTIONAL scope, OPTIONAL !, and REQUIRED terminal colon and space. +- The type feat MUST be used when a commit adds a new feature to your application or library. +- The type fix MUST be used when a commit represents a bug fix for your application. +- A scope MAY be provided after a type. A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., fix(parser): +- A description MUST immediately follow the colon and space after the type/scope prefix. The description is a short summary of the code changes, e.g., fix: array parsing issue when multiple spaces were contained in string. +- A longer commit body MAY be provided after the short description, providing additional contextual information about the code changes. The body MUST begin one blank line after the description. +- A commit body is free-form and MAY consist of any number of newline separated paragraphs. +- One or more footers MAY be provided one blank line after the body. Each footer MUST consist of a word token, followed by either a :<space> or <space># separator, followed by a string value (this is inspired by the git trailer convention). +- A footer’s token MUST use - in place of whitespace characters, e.g., Acked-by (this helps differentiate the footer section from a multi-paragraph body). An exception is made for BREAKING CHANGE, which MAY also be used as a token. +- A footer’s value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed. +- Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer. +- If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description, e.g., BREAKING CHANGE: environment variables now take precedence over config files. +If included in the type/scope prefix, breaking changes MUST be indicated by a ! immediately before the :. If ! is used, BREAKING CHANGE: MAY be omitted from the footer section, and the commit description SHALL be used to describe the breaking change. +- Types other than feat and fix MAY be used in your commit messages, e.g., docs: updated ref docs. +- The units of information that make up Conventional Commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase. +- BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer. + +## Why Should We Use It? + +- Automatic changelog generation +- The context information that refers to business initiative when it's needed +- Noticeable breaking changes +- Forces us to write better commit messages (no more vague 'fix', 'refactor' commits) +- Bumping version precisely +- Making it easier to contribute to the projects by allowing contributors to explore a more structured commit history + +## Changelog Generation + +### Why Changelog? + +A changelog is a file that contains a curated, chronologically ordered list of notable changes for each version of a project to make it easier for users and contributors. + +For more information, see the [Keep a Changelog](https://keepachangelog.com/) standard. + +### Why Generate Changelogs via Conventional Commits? + +It's hard to maintain changelogs by hand and most of the time it fails. Manual changelog updates lead to: + +- Discrepancy between docs and actual versions +- Missing breaking changes +- Outdated changelogs + +You can automate the process of generating changelogs via GitHub Actions or locally via git hooks, which speeds up the process significantly. + +## Bump the Version Precisely + +### Benefits of Bumping Version Through Conventional Commits + +- We shouldn't depend on one owner who knows every change between releases +- Every contributor should decide the impact of their changes during the development process +- You can auto-bump the version once it's merged to a specific branch (no more forgotten version updates) +- See [Conventional Commits Version Bump](https://github.com/marketplace/actions/conventional-commits-version-bump) GitHub Action +- Speeds up the process +- Prevents human mistakes + +**Major Version Bump** + +```text +refactor!: drop support for Node 6 +``` + +**Minor Version Bump** + +```text +feat(SHOPPER-000): introduce OrderMonitor v2 +``` + +**Patch Version Bump** + +```text +fix(SHOPPER-000): correct minor typos in code +``` + +## How About Squash Merges? + +Why do we need squash merges if we have good commit messages? + +### Pros + +- Every squash commit linked to PR +- Cleaner git history +- Easy roll-back + +### Cons + +- It changes commit history, which can cause conflicts +- It's hard to understand what actually changed +- Sometimes what you commit is not related to the purpose of the PR |