From 5c2d41c290031bedd39684a56dcfe1e2a02defe0 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:17:42 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 11 +++ README.md | 3 + SKILL.md | 174 +++++++++++++++++++++++++++++++++++++ plugin.lock.json | 49 +++++++++++ references/full-spec.md | 159 +++++++++++++++++++++++++++++++++ 5 files changed, 396 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 SKILL.md create mode 100644 plugin.lock.json create mode 100644 references/full-spec.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..e9b51e8 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "conventional-commits", + "description": "Format git commit messages following Conventional Commits 1.0.0 specification. Use when the user asks to commit changes, create a git commit, or mentions committing code. Ensures consistent, semantic commit messages that support automated changelog generation and semantic versioning.", + "version": "1.0.0", + "author": { + "name": "Alberto Leal" + }, + "skills": [ + "./" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..92f47bf --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# conventional-commits + +Format git commit messages following Conventional Commits 1.0.0 specification. Use when the user asks to commit changes, create a git commit, or mentions committing code. Ensures consistent, semantic commit messages that support automated changelog generation and semantic versioning. diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..6e0b171 --- /dev/null +++ b/SKILL.md @@ -0,0 +1,174 @@ +--- +name: conventional-commits +description: "Format git commit messages following Conventional Commits 1.0.0 specification. Use when the user asks to commit changes, create a git commit, or mentions committing code. Ensures consistent, semantic commit messages that support automated changelog generation and semantic versioning." +license: MIT +--- + +# Conventional Commits + +Format all git commit messages according to the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/) specification. + +## Commit Message Format + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +## Type Reference + +| Type | When to Use | SemVer | +|------|-------------|--------| +| `feat` | New feature | MINOR | +| `fix` | Bug fix | PATCH | +| `docs` | Documentation only | - | +| `style` | Formatting, whitespace (no code change) | - | +| `refactor` | Code restructuring (no feature/fix) | - | +| `perf` | Performance improvement | - | +| `test` | Adding/fixing tests | - | +| `build` | Build system, dependencies | - | +| `ci` | CI/CD configuration | - | +| `chore` | Maintenance, tooling | - | +| `revert` | Reverting previous commit | - | + +## Decision Framework + +When determining commit type, ask: + +- Does it add new functionality? → `feat` +- Does it fix broken functionality? → `fix` +- Does it only affect documentation? → `docs` +- Does it improve performance? → `perf` +- Does it restructure code without changing behavior? → `refactor` +- Does it only change code style/formatting? → `style` +- Does it add/modify tests? → `test` +- Does it change build system or dependencies? → `build` +- Does it change CI/CD configuration? → `ci` +- Is it maintenance or tooling? → `chore` + +## Message Best Practices + +### Description (first line) +- Keep under 50 characters +- Use imperative mood ("add" not "added") +- Don't capitalize first letter +- No period at end + +### Scope +- Use clear, consistent names: `feat(auth):`, `fix(api):`, `docs(readme):` + +### Body +- Include when change requires explanation +- Explain why the change was made +- Describe what problem it solves +- Wrap at 72 characters per line + +### Footers +- `Fixes #123` - Reference issues +- `Co-authored-by: Name ` - Credit contributors +- `BREAKING CHANGE: description` - Breaking changes +- `Refs: #456, #789` - Related issues + +## Breaking Changes + +Indicate breaking changes using either method: + +``` +feat!: remove deprecated API endpoint + +feat(api)!: change authentication flow + +fix: update validation logic + +BREAKING CHANGE: validation now rejects empty strings +``` + +## Command Execution + +**Critical**: Use single quotes to avoid shell escaping issues with `!`: + +```bash +# Correct - single quotes +git commit -m 'feat!: add new authentication flow' + +# Incorrect - backslash escaping (DO NOT USE) +git commit -m "feat\!: add new authentication flow" +``` + +For multi-line messages, use HEREDOC: + +```bash +git commit -m "$(cat <<'EOF' +feat(auth): add OAuth2 support + +Implement OAuth2 authentication flow with support for +Google and GitHub providers. + +BREAKING CHANGE: removes legacy session-based auth +EOF +)" +``` + +## Workflow + +1. Check for staged changes: `git diff --cached --stat` +2. If nothing staged: stage with `git add` first +3. Review changes: `git diff --cached` +4. Check recent style: `git log --oneline -5` +5. Determine type using decision framework +6. Write message following best practices +7. Execute commit with single quotes +8. Verify: `git log -1` + +## Quality Checks + +Before committing, verify: + +- [ ] Message accurately describes the changes +- [ ] Type correctly categorizes the change +- [ ] Scope (if used) is meaningful and consistent +- [ ] Breaking changes are properly marked with `!` or footer +- [ ] Description is clear and under 50 characters +- [ ] Body wraps at 72 characters (if present) + +## Examples + +**Simple fix:** +``` +fix: prevent null pointer in user lookup +``` + +**Feature with scope:** +``` +feat(api): add rate limiting to endpoints +``` + +**With body:** +``` +refactor: extract validation into separate module + +Move validation logic from controllers to dedicated +validator classes for better testability and reuse. +``` + +**Breaking change:** +``` +feat!: upgrade to v2 API format + +BREAKING CHANGE: response structure changed from +{data: [...]} to {items: [...], meta: {...}} +``` + +**With issue reference:** +``` +fix(auth): resolve token refresh race condition + +Fixes #234 +``` + +## Full Specification + +For the complete Conventional Commits 1.0.0 specification including all rules and FAQ, see [references/full-spec.md](references/full-spec.md). diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..a8fe922 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,49 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:dashed/claude-marketplace:plugins/conventional-commits", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "544d6dd95fcca2d4dd895c1ab6c863591aa08f70", + "treeHash": "8a9fe6a62f455f41787d2665c667b443ae696ec4b61e7a4fcbfe2b1ef3edd337", + "generatedAt": "2025-11-28T10:16:04.833409Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "conventional-commits", + "description": "Format git commit messages following Conventional Commits 1.0.0 specification. Use when the user asks to commit changes, create a git commit, or mentions committing code. Ensures consistent, semantic commit messages that support automated changelog generation and semantic versioning.", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "25a89228ce0f53b3ad5af449bd209fcaeb50bd972551fd47598b38937ee3e3a3" + }, + { + "path": "SKILL.md", + "sha256": "b3797cb0371263e5a2335eaa6fc5954047a6ea82ce0f29fb594e1ed14a06b7ef" + }, + { + "path": "references/full-spec.md", + "sha256": "2d55162375f4b25687604f3927a45bde9b968325e4748753d23922c57ef0926e" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "afe5bdd27b0a08693aff4db0121f9b267a4c34a95f44043641c1341a3abf1de4" + } + ], + "dirSha256": "8a9fe6a62f455f41787d2665c667b443ae696ec4b61e7a4fcbfe2b1ef3edd337" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/references/full-spec.md b/references/full-spec.md new file mode 100644 index 0000000..259a8cf --- /dev/null +++ b/references/full-spec.md @@ -0,0 +1,159 @@ +# Conventional Commits 1.0.0 - Full Specification + +Source: https://www.conventionalcommits.org/en/v1.0.0/ + +## Summary + +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](http://semver.org), by describing the features, fixes, and breaking changes made in commit messages. + +## Message Structure + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +## Structural Elements + +1. **fix:** a commit of the _type_ `fix` patches a bug in your codebase (correlates with `PATCH` in Semantic Versioning). + +2. **feat:** a commit of the _type_ `feat` introduces a new feature to the codebase (correlates with `MINOR` in Semantic Versioning). + +3. **BREAKING CHANGE:** a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlates with `MAJOR` in Semantic Versioning). A BREAKING CHANGE can be part of commits of any _type_. + +4. **Other types:** `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, and others are allowed. + +5. **Footers** other than `BREAKING CHANGE: ` may be provided and follow git trailer format. + +A scope may be provided after a type for additional context: `feat(parser): add ability to parse arrays`. + +## Examples + +### Commit message with description and breaking change footer +``` +feat: allow provided config object to extend other configs + +BREAKING CHANGE: `extends` key in config file is now used for extending other config files +``` + +### Commit message with `!` to draw attention to breaking change +``` +feat!: send an email to the customer when a product is shipped +``` + +### Commit message with scope and `!` to draw attention to breaking change +``` +feat(api)!: send an email to the customer when a product is shipped +``` + +### Commit message with both `!` and BREAKING CHANGE footer +``` +chore!: drop support for Node 6 + +BREAKING CHANGE: use JavaScript features not available in Node 6. +``` + +### Commit message with no body +``` +docs: correct spelling of CHANGELOG +``` + +### Commit message with scope +``` +feat(lang): add Polish language +``` + +### Commit message with multi-paragraph body and multiple footers +``` +fix: prevent racing of requests + +Introduce a request id and a reference to latest request. Dismiss +incoming responses other than from latest request. + +Remove timeouts which were used to mitigate the racing issue but are +obsolete now. + +Reviewed-by: Z +Refs: #123 +``` + +## Specification Rules + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are interpreted as described in RFC 2119. + +1. 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. + +2. The type `feat` MUST be used when a commit adds a new feature to your application or library. + +3. The type `fix` MUST be used when a commit represents a bug fix for your application. + +4. 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):` + +5. 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_. + +6. 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. + +7. A commit body is free-form and MAY consist of any number of newline separated paragraphs. + +8. 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 `:` or `#` separator, followed by a string value. + +9. A footer's token MUST use `-` in place of whitespace characters, e.g., `Acked-by`. An exception is made for `BREAKING CHANGE`, which MAY also be used as a token. + +10. A footer's value MAY contain spaces and newlines, and parsing MUST terminate when the next valid footer token/separator pair is observed. + +11. Breaking changes MUST be indicated in the type/scope prefix of a commit, or as an entry in the footer. + +12. If included as a footer, a breaking change MUST consist of the uppercase text BREAKING CHANGE, followed by a colon, space, and description. + +13. 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. + +14. Types other than `feat` and `fix` MAY be used in your commit messages. + +15. 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. + +16. BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE when used as a token in a footer. + +## SemVer Relationship + +| Commit Type | SemVer Impact | +|-------------|---------------| +| `fix` | PATCH release | +| `feat` | MINOR release | +| Any type with `BREAKING CHANGE` | MAJOR release | + +## FAQ + +### How should I deal with commit messages in the initial development phase? + +Proceed as if you've already released the product. Typically *somebody*, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks etc. + +### Are the types in the commit title uppercase or lowercase? + +Any casing may be used, but it's best to be consistent. Lowercase is conventional. + +### What do I do if the commit conforms to more than one of the commit types? + +Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive us to make more organized commits and PRs. + +### What do I do if I accidentally use the wrong commit type? + +**Wrong type of the spec (e.g., `fix` instead of `feat`):** Use `git rebase -i` to edit the commit history before merging or releasing. + +**Type not of the spec (e.g., `feet` instead of `feat`):** The commit will be missed by tools based on the spec, but it's not the end of the world. + +### Do all my contributors need to use the Conventional Commits specification? + +No! If you use a squash based workflow, lead maintainers can clean up the commit messages as they're merged. + +### How does Conventional Commits handle revert commits? + +Use the `revert` type with a footer referencing the commit SHAs being reverted: + +``` +revert: let us never again speak of the noodle incident + +Refs: 676104e, a215868 +```