From 891d6a1cb791f5a3f6aa43581c7019821ca148e9 Mon Sep 17 00:00:00 2001 From: baxyz Date: Fri, 22 May 2026 16:09:23 +0200 Subject: [PATCH 1/5] =?UTF-8?q?docs:=20=F0=9F=93=9D=20update=20commit=20me?= =?UTF-8?q?ssage=20instructions=20and=20scopes=20in=20AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vscode/settings.json | 7 ++++++- AGENTS.md | 2 +- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index f547920..be5dfef 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,5 +3,10 @@ "conventional-commits", "deps", "CI-CD" + ], + "github.copilot.chat.commitMessageGeneration.instructions": [ + { + "text": "Commit messages for this repository must use Conventional Commits + gitmoji: `(): `. Scope is optional; when used, pick ONE of: conventional-commits, deps, CI-CD. Never invent a scope. Type\u2192emoji: feat\u2192\u2728, fix\u2192\uD83D\uDC1B, docs\u2192\uD83D\uDCDD, refactor\u2192\u267B\uFE0F, test\u2192\u2705, chore\u2192\uD83D\uDD27, perf\u2192\u26A1\uFE0F, style\u2192\uD83D\uDC84, ci\u2192\uD83D\uDC77, build\u2192\uD83D\uDCE6\uFE0F, revert\u2192\u23EA\uFE0F (pick the most specific: \uD83D\uDE91\uFE0F hotfix, \u2B06\uFE0F dep upgrade, \uD83E\uDE79 trivial, \uD83D\uDD25 remove code). Always include exactly ONE emoji. Description \u226472 chars, English, lowercase, imperative, no period. Multiple changes \u2192 bullet list in body." + } ] -} +} \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index cf969a2..df6492a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,7 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/) with a gitmo **Format:** `(): ` -**Scopes:** conventional-commits, CI-CD +**Scopes:** defined in `.vscode/settings.json` (`conventionalCommits.scopes`) | Type | Primary | Alternatives (gitmoji.dev) | When to use | |------|---------|---------------------------|-------------| From b745ffec54eaf3978820126cf5638486418d312d Mon Sep 17 00:00:00 2001 From: baxyz Date: Fri, 22 May 2026 16:28:08 +0200 Subject: [PATCH 2/5] =?UTF-8?q?chore:=20=F0=9F=94=A7=20update=20commit=20m?= =?UTF-8?q?essage=20instructions=20and=20add=20copilot-commit.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vscode/copilot-commit.md | 34 ++++++++++++++++++++++++++++++++++ .vscode/settings.json | 2 +- 2 files changed, 35 insertions(+), 1 deletion(-) create mode 100644 .vscode/copilot-commit.md diff --git a/.vscode/copilot-commit.md b/.vscode/copilot-commit.md new file mode 100644 index 0000000..ff519c5 --- /dev/null +++ b/.vscode/copilot-commit.md @@ -0,0 +1,34 @@ + + + +Commit messages for the **action** repository must use Conventional Commits + gitmoji: + +`(): ` + +**Allowed scopes** (pick one, or omit the scope entirely): +- `conventional-commits` +- `deps` +- `CI-CD` + +Never invent a scope that is not in the list above. + +**Type โ†’ gitmoji** โ€” pick the most specific emoji that fits the change: + +| Type | Primary | More specific alternatives | +|------|---------|---------------------------| +| `feat` | โœจ | ๐Ÿšธ UX ยท โ™ฟ๏ธ a11y ยท ๐ŸŒ i18n ยท ๐Ÿ’ฌ text/literals | +| `fix` | ๐Ÿ› | ๐Ÿš‘๏ธ hotfix ยท ๐Ÿ”’๏ธ security ยท ๐Ÿฉน trivial ยท ๐Ÿฅ… caught errors ยท ๐Ÿšจ linter warnings ยท โœ๏ธ typo | +| `docs` | ๐Ÿ“ | ๐Ÿ’ก source comments ยท ๐Ÿ“„ license | +| `refactor` | โ™ป๏ธ | ๐ŸŽจ structure ยท ๐Ÿ”ฅ remove code ยท โšฐ๏ธ dead code ยท ๐Ÿšš move/rename | +| `test` | โœ… | ๐Ÿงช add failing test ยท ๐Ÿ’š fix CI test | +| `chore` | ๐Ÿ”ง | ๐Ÿ”– tag/release ยท ๐Ÿ“Œ pin deps ยท ๐Ÿฉบ healthcheck ยท ๐Ÿ™ˆ gitignore | +| `perf` | โšก๏ธ | | +| `style` | ๐Ÿ’„ | ๐ŸŽจ code style | +| `ci` | ๐Ÿ‘ท | ๐Ÿ’š fix CI | +| `build` | ๐Ÿ“ฆ๏ธ | โž• add dep ยท โž– remove dep ยท โฌ†๏ธ upgrade dep ยท โฌ‡๏ธ downgrade dep | +| `revert` | โช๏ธ | | + +**Rules:** +- Always include exactly **one** emoji, placed between `:` and the description +- Description: โ‰ค72 chars ยท English ยท lowercase ยท imperative mood ยท no trailing period +- Multiple logical changes โ†’ keep the dominant type in the subject line and use a bullet list in the body diff --git a/.vscode/settings.json b/.vscode/settings.json index be5dfef..3c9d1fc 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -6,7 +6,7 @@ ], "github.copilot.chat.commitMessageGeneration.instructions": [ { - "text": "Commit messages for this repository must use Conventional Commits + gitmoji: `(): `. Scope is optional; when used, pick ONE of: conventional-commits, deps, CI-CD. Never invent a scope. Type\u2192emoji: feat\u2192\u2728, fix\u2192\uD83D\uDC1B, docs\u2192\uD83D\uDCDD, refactor\u2192\u267B\uFE0F, test\u2192\u2705, chore\u2192\uD83D\uDD27, perf\u2192\u26A1\uFE0F, style\u2192\uD83D\uDC84, ci\u2192\uD83D\uDC77, build\u2192\uD83D\uDCE6\uFE0F, revert\u2192\u23EA\uFE0F (pick the most specific: \uD83D\uDE91\uFE0F hotfix, \u2B06\uFE0F dep upgrade, \uD83E\uDE79 trivial, \uD83D\uDD25 remove code). Always include exactly ONE emoji. Description \u226472 chars, English, lowercase, imperative, no period. Multiple changes \u2192 bullet list in body." + "file": ".vscode/copilot-commit.md" } ] } \ No newline at end of file From 421950d1c3fae54e7b7540bca896572d102cae95 Mon Sep 17 00:00:00 2001 From: baxyz Date: Sat, 27 Jun 2026 15:09:44 +0000 Subject: [PATCH 3/5] =?UTF-8?q?docs:=20=F0=9F=93=9D=20update=20AGENTS.md?= =?UTF-8?q?=20for=20clarity=20and=20structure?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 142 +++++++++--------------------------------------------- 1 file changed, 22 insertions(+), 120 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index df6492a..ebab7c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,138 +1,40 @@ -# AGENTS.md - GitHub Actions +# AGENTS.md โ€” action -## โ›” CRITICAL RESTRICTIONS - -- **NEVER execute `git push`** - The user will push manually after review -- **NEVER use GPT models** - Use Claude models only (claude-sonnet-4, Claude Opus 4.5) -- **Everything in English** - Code, comments, commits, documentation, logs, PR descriptions - -## Organization Context - -**helpers4** is a collection of open-source utilities across 5 repos: `typescript`, `devcontainer`, `action` (this repo), `website`, `.github`. All licensed LGPL-3.0. - -## Commit Messages - -Follow [Conventional Commits](https://www.conventionalcommits.org/) with a gitmoji between the scope and the description. - -**Format:** `(): ` - -**Scopes:** defined in `.vscode/settings.json` (`conventionalCommits.scopes`) - -| Type | Primary | Alternatives (gitmoji.dev) | When to use | -|------|---------|---------------------------|-------------| -| feat | โœจ | ๐Ÿšธ UX, โ™ฟ๏ธ a11y, ๐ŸŒ i18n, ๐Ÿ’ฌ text/literals | New feature | -| fix | ๐Ÿ› | ๐Ÿš‘๏ธ hotfix, ๐Ÿ”’๏ธ security, ๐Ÿฉน trivial, ๐Ÿฅ… errors, ๐Ÿšจ warnings, โœ๏ธ typo | Bug fix | -| docs | ๐Ÿ“ | ๐Ÿ’ก source comments, ๐Ÿ“„ license | Documentation | -| refactor | โ™ป๏ธ | ๐ŸŽจ structure, ๐Ÿ”ฅ remove code, โšฐ๏ธ dead code, ๐Ÿšš move/rename | Code refactoring | -| test | โœ… | ๐Ÿงช failing test, ๐Ÿ’š fix CI test | Tests | -| chore | ๐Ÿ”ง | ๐Ÿ™ˆ gitignore, ๐Ÿ”– tag/release, ๐Ÿ“Œ pin deps, ๐Ÿฉบ healthcheck | Maintenance | -| perf | โšก๏ธ | โ€” | Performance | -| style | ๐Ÿ’„ | ๐ŸŽจ code style | Code style / UI | -| ci | ๐Ÿ‘ท | ๐Ÿ’š fix CI | CI/CD | -| build | ๐Ÿ“ฆ๏ธ | โž• add dep, โž– remove dep, โฌ†๏ธ upgrade dep, โฌ‡๏ธ downgrade dep | Build system | -| revert | โช๏ธ | โ€” | Revert | - -> Pick the **most specific** gitmoji that matches the change. The primary is the safe default; reach for an alternative when it adds real signal. Full list: https://gitmoji.dev - -**Examples:** -- `feat(conventional-commits): โœจ add PR title validation` -- `fix(CI-CD): ๐Ÿ› fix checkout depth` -- `docs: ๐Ÿ“ update usage examples` - ---- +โ†’ [Org-wide rules](https://github.com/helpers4/.dev/blob/main/AGENTS.md): restrictions ยท commit format ยท license headers ## This Repository -**Purpose:** Reusable GitHub Actions for the helpers4 organization and external users. - -### Project Structure +**Purpose:** Reusable GitHub Actions published at `helpers4/action/@v1`. -``` +```text action/ -โ”œโ”€โ”€ conventional-commits/ -โ”‚ โ”œโ”€โ”€ action.yml # Action metadata and inputs -โ”‚ โ”œโ”€โ”€ README.md # Usage documentation -โ”‚ โ””โ”€โ”€ scripts/ -โ”‚ โ””โ”€โ”€ validate.sh # Main validation logic -โ”œโ”€โ”€ AGENTS.md # This file -โ”œโ”€โ”€ LICENSE # LGPL-3.0 -โ””โ”€โ”€ README.md +โ””โ”€โ”€ conventional-commits/ + โ”œโ”€โ”€ action.yml # composite action โ€” inputs, outputs + โ”œโ”€โ”€ README.md + โ””โ”€โ”€ scripts/ + โ””โ”€โ”€ validate.sh # set -euo pipefail ยท inputs via INPUT_* env vars ``` -### Conventional Commits Action +**conventional-commits action โ€” key inputs:** -**Type:** Composite action (Bash) +| Input | Default | Notes | +| ----- | ------- | ----- | +| `base-sha` / `head-sha` | โ€” | commit range to validate | +| `types` | `feat\|fix\|docs\|...` | pipe-separated regex | +| `scopes` | โ€” | pipe-separated regex | +| `require-scope` | `false` | | +| `validate-pr-title` | `false` | | +| `pr-comment` | `none` | `none\|error\|success\|both` | -**Inputs:** -| Input | Default | Description | -|-------|---------|-------------| -| `checkout` | `true` | Run actions/checkout | -| `base-sha` | โ€” | Base commit SHA | -| `head-sha` | โ€” | Head commit SHA | -| `types` | `feat\|fix\|docs\|...` | Allowed commit types (pipe-separated regex) | -| `scopes` | โ€” | Allowed scopes (pipe-separated regex) | -| `require-scope` | `false` | Require scope in every message | -| `ignore-commits` | โ€” | Patterns to ignore (regex, newline-separated) | -| `validate-pr-title` | `false` | Also validate PR title | -| `pr-comment` | `none` | When to PR comment: none, error, success, both | +Output: `status` โ†’ `success` or `failure`. +SHA fallback chain: `GITHUB_BASE_REF` โ†’ `remotes/origin/$GITHUB_BASE_REF` โ†’ `main` โ†’ `master`. -**Output:** `status` โ€” `success` or `failure` +**Adding a new action:** `/action.yml` + `scripts/` + `README.md` + update root `README.md` + add shellcheck/test jobs to `pr-validation.yml` + add scope to `.vscode/settings.json`. -### Script Conventions - -- Bash strict mode: `set -euo pipefail` -- Inputs via environment: `INPUT_BASE_SHA`, `INPUT_HEAD_SHA`, etc. -- Fallback logic: `GITHUB_BASE_REF` โ†’ `remotes/origin/$GITHUB_BASE_REF` โ†’ `main` โ†’ `master` -- Commits via `git rev-list`, each message validated individually -- Scope validation uses regex patterns - -### Usage Example - -```yaml -- name: Validate conventional commits - uses: helpers4/action/conventional-commits@v1 - with: - base-sha: ${{ github.event.pull_request.base.sha }} - head-sha: ${{ github.event.pull_request.head.sha }} - types: 'feat|fix|refactor' - require-scope: true -``` - -### CI/CD Workflows - -| Workflow | Trigger | Jobs | -|----------|---------|------| -| `pr-validation.yml` | Pull request โ†’ main | conventional-commits, shellcheck, test-action, pr-comment | - -- **conventional-commits** โ€” Validates PR commit messages against conventional commit format -- **shellcheck** โ€” Lints `validate.sh` with ShellCheck -- **test-action** โ€” Syntax check and basic validation of the action script -- **pr-comment** โ€” Posts/updates a status summary comment on the PR - -### Adding a New Action - -1. Create `/action.yml` -2. Create `/scripts/` with implementation -3. Create `/README.md` -4. Update root `README.md` -5. **Update `.github/workflows/pr-validation.yml`** โ€” Add shellcheck/test jobs for the new action -6. Update this `AGENTS.md` (scopes + structure) - -### License Header (required on all scripts) +**License header (all scripts):** ```bash # This file is part of helpers4. # Copyright (C) 2025 baxyz # SPDX-License-Identifier: LGPL-3.0-or-later ``` -## Repository Links - -- TypeScript: https://github.com/helpers4/typescript -- DevContainer: https://github.com/helpers4/devcontainer -- Actions: https://github.com/helpers4/action -- Website: https://github.com/helpers4/website -- Organization: https://github.com/helpers4 - -## Questions? - -If you need clarification on any aspect, open an issue or comment on the PR. We're here to help! From 5223f7059ffb9363a03b8b5b832068dc6713c6d4 Mon Sep 17 00:00:00 2001 From: baxyz Date: Sat, 27 Jun 2026 20:00:25 +0000 Subject: [PATCH 4/5] =?UTF-8?q?chore:=20=F0=9F=94=A7=20remove=20copilot=20?= =?UTF-8?q?commit=20message=20instructions=20and=20update=20settings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vscode/copilot-commit.md | 34 ---------------------------------- .vscode/settings.json | 13 +------------ scopes.json | 5 +++++ 3 files changed, 6 insertions(+), 46 deletions(-) delete mode 100644 .vscode/copilot-commit.md create mode 100644 scopes.json diff --git a/.vscode/copilot-commit.md b/.vscode/copilot-commit.md deleted file mode 100644 index ff519c5..0000000 --- a/.vscode/copilot-commit.md +++ /dev/null @@ -1,34 +0,0 @@ - - - -Commit messages for the **action** repository must use Conventional Commits + gitmoji: - -`(): ` - -**Allowed scopes** (pick one, or omit the scope entirely): -- `conventional-commits` -- `deps` -- `CI-CD` - -Never invent a scope that is not in the list above. - -**Type โ†’ gitmoji** โ€” pick the most specific emoji that fits the change: - -| Type | Primary | More specific alternatives | -|------|---------|---------------------------| -| `feat` | โœจ | ๐Ÿšธ UX ยท โ™ฟ๏ธ a11y ยท ๐ŸŒ i18n ยท ๐Ÿ’ฌ text/literals | -| `fix` | ๐Ÿ› | ๐Ÿš‘๏ธ hotfix ยท ๐Ÿ”’๏ธ security ยท ๐Ÿฉน trivial ยท ๐Ÿฅ… caught errors ยท ๐Ÿšจ linter warnings ยท โœ๏ธ typo | -| `docs` | ๐Ÿ“ | ๐Ÿ’ก source comments ยท ๐Ÿ“„ license | -| `refactor` | โ™ป๏ธ | ๐ŸŽจ structure ยท ๐Ÿ”ฅ remove code ยท โšฐ๏ธ dead code ยท ๐Ÿšš move/rename | -| `test` | โœ… | ๐Ÿงช add failing test ยท ๐Ÿ’š fix CI test | -| `chore` | ๐Ÿ”ง | ๐Ÿ”– tag/release ยท ๐Ÿ“Œ pin deps ยท ๐Ÿฉบ healthcheck ยท ๐Ÿ™ˆ gitignore | -| `perf` | โšก๏ธ | | -| `style` | ๐Ÿ’„ | ๐ŸŽจ code style | -| `ci` | ๐Ÿ‘ท | ๐Ÿ’š fix CI | -| `build` | ๐Ÿ“ฆ๏ธ | โž• add dep ยท โž– remove dep ยท โฌ†๏ธ upgrade dep ยท โฌ‡๏ธ downgrade dep | -| `revert` | โช๏ธ | | - -**Rules:** -- Always include exactly **one** emoji, placed between `:` and the description -- Description: โ‰ค72 chars ยท English ยท lowercase ยท imperative mood ยท no trailing period -- Multiple logical changes โ†’ keep the dominant type in the subject line and use a bullet list in the body diff --git a/.vscode/settings.json b/.vscode/settings.json index 3c9d1fc..0967ef4 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,12 +1 @@ -{ - "conventionalCommits.scopes": [ - "conventional-commits", - "deps", - "CI-CD" - ], - "github.copilot.chat.commitMessageGeneration.instructions": [ - { - "file": ".vscode/copilot-commit.md" - } - ] -} \ No newline at end of file +{} diff --git a/scopes.json b/scopes.json new file mode 100644 index 0000000..0385c54 --- /dev/null +++ b/scopes.json @@ -0,0 +1,5 @@ +[ + "conventional-commits", + "deps", + "CI-CD" +] From c39affcd92ca72c91d8f6b098ace20f340ee53a4 Mon Sep 17 00:00:00 2001 From: baxyz Date: Sat, 27 Jun 2026 20:01:09 +0000 Subject: [PATCH 5/5] =?UTF-8?q?feat(conventional-commits):=20=F0=9F=93=A6?= =?UTF-8?q?=20add=20support=20for=20auto-reading=20scopes=20from=20a=20JSO?= =?UTF-8?q?N=20file=20in=20validation=20script?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- conventional-commits/action.yml | 7 ++++++- conventional-commits/scripts/validate.sh | 11 ++++++++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/conventional-commits/action.yml b/conventional-commits/action.yml index 82185bc..561945c 100644 --- a/conventional-commits/action.yml +++ b/conventional-commits/action.yml @@ -28,8 +28,12 @@ inputs: description: "Allowed scopes (regex patterns, pipe-separated) - empty means all scopes allowed" required: false default: "" + scopes-file: + description: "Path to agnostic scopes JSON file (array) to auto-read when scopes input is empty โ€” takes priority over vscode-settings" + required: false + default: "scopes.json" vscode-settings: - description: "Path to VS Code settings.json to auto-read conventionalCommits.scopes when scopes input is empty" + description: "Path to VS Code settings.json to auto-read conventionalCommits.scopes when scopes input and scopes-file are both absent" required: false default: ".vscode/settings.json" require-scope: @@ -77,6 +81,7 @@ runs: INPUT_HEAD_SHA: ${{ inputs.head-sha }} INPUT_TYPES: ${{ inputs.types }} INPUT_SCOPES: ${{ inputs.scopes }} + INPUT_SCOPES_FILE: ${{ inputs.scopes-file }} INPUT_VSCODE_SETTINGS: ${{ inputs.vscode-settings }} INPUT_REQUIRE_SCOPE: ${{ inputs.require-scope }} INPUT_IGNORE_COMMITS: ${{ inputs.ignore-commits }} diff --git a/conventional-commits/scripts/validate.sh b/conventional-commits/scripts/validate.sh index b92fb4b..7493fa5 100755 --- a/conventional-commits/scripts/validate.sh +++ b/conventional-commits/scripts/validate.sh @@ -9,13 +9,22 @@ BASE_SHA="${INPUT_BASE_SHA:-}" HEAD_SHA="${INPUT_HEAD_SHA:-}" TYPES="${INPUT_TYPES:-feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert}" SCOPES="${INPUT_SCOPES:-}" +SCOPES_FILE="${INPUT_SCOPES_FILE:-scopes.json}" VSCODE_SETTINGS="${INPUT_VSCODE_SETTINGS:-.vscode/settings.json}" REQUIRE_SCOPE="${INPUT_REQUIRE_SCOPE:-false}" IGNORE_COMMITS="${INPUT_IGNORE_COMMITS:-}" VALIDATE_PR_TITLE="${INPUT_VALIDATE_PR_TITLE:-false}" PR_COMMENT="${INPUT_PR_COMMENT:-error}" -# Auto-read scopes from VS Code settings if not explicitly provided +# Priority: scopes (explicit) > scopes-file > vscode-settings +if [[ -z "$SCOPES" && -f "$SCOPES_FILE" ]]; then + FILE_SCOPES=$(jq -r '.[]' "$SCOPES_FILE" | paste -sd '|' || echo "") + if [[ -n "$FILE_SCOPES" ]]; then + echo "Auto-detected scopes from $SCOPES_FILE: $FILE_SCOPES" + SCOPES="$FILE_SCOPES" + fi +fi + if [[ -z "$SCOPES" && -f "$VSCODE_SETTINGS" ]]; then # Strip JSONC line comments (// ...) and trailing commas before parsing with jq VSCODE_SCOPES=$(sed 's|//[^"]*$||g; s|,\s*\([}\]]\)|\1|g' "$VSCODE_SETTINGS" \