From dd3f220a7d510bb4d35b1be87d7f33c5f66b3c55 Mon Sep 17 00:00:00 2001 From: Ben Rozsa Date: Sun, 14 Sep 2025 21:35:51 +0200 Subject: [PATCH 1/5] ci(shellcheck): install and run native shellcheck on ubuntu-latest Replace ludeeus/action-shellcheck action with apt-based installation and direct invocation. Avoids tag resolution errors (e.g., 'unable to find version v2') and removes third-party action dependency. --- .github/workflows/shellcheck.yml | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml index 249fb9c..f47fd5d 100644 --- a/.github/workflows/shellcheck.yml +++ b/.github/workflows/shellcheck.yml @@ -35,9 +35,25 @@ jobs: steps: - name: Checkout uses: actions/checkout@v4 + - name: Install ShellCheck + run: | + sudo apt-get update + sudo apt-get install -y shellcheck - name: Run ShellCheck - uses: ludeeus/action-shellcheck@v2 - with: - severity: error - check_together: true - path: . + shell: bash + run: | + set -euo pipefail + mapfile -t files < <(git ls-files \ + '**/*.sh' \ + '**/*.bash' \ + '**/*.zsh' \ + '**/.bashrc' \ + '**/.bash_aliases' \ + '**/.zshrc' \ + '**/.profile') + if [ "${#files[@]}" -eq 0 ]; then + echo "No shell files to check." + exit 0 + fi + echo "Checking ${#files[@]} file(s) with ShellCheck..." + shellcheck -S error -x "${files[@]}" From c41a3a3030c1e36f193dedae8234e19bb5175685 Mon Sep 17 00:00:00 2001 From: Ben Rozsa Date: Sun, 14 Sep 2025 21:45:05 +0200 Subject: [PATCH 2/5] docs: add AGENTS.md house rules; add PR template and issue forms Add persistent guidance for assistants (no direct pushes, PR workflow, Conventional Commits, CI). Add PR template and issue forms (bug, feature) to enforce structure. --- .github/ISSUE_TEMPLATE/bug_report.yml | 38 +++++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 5 +++ .github/ISSUE_TEMPLATE/feature_request.yml | 31 ++++++++++++++ .github/pull_request_template.md | 24 +++++++++++ AGENTS.md | 48 ++++++++++++++++++++++ 5 files changed, 146 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 AGENTS.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..df3d2c8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,38 @@ +name: Bug report +description: Report a problem to help us improve +labels: [bug] +body: + - type: textarea + id: summary + attributes: + label: Summary + description: What happened? What did you expect? + placeholder: Clear, concise description of the bug + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps To Reproduce + description: List exact steps and any commands run + placeholder: | + 1. … + 2. … + 3. … + validations: + required: true + - type: textarea + id: env + attributes: + label: Environment + description: OS, shell, relevant versions + placeholder: macOS 14 / Fedora 40, zsh 5.9, VS Code 1.xx + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs / Screenshots + description: Paste errors or attach screenshots + render: shell + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..fed5834 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Questions + url: https://github.com/benrozsa/dotfiles/discussions + about: Ask usage questions and get support here diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..cd8a61c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,31 @@ +name: Feature request +description: Suggest an idea or improvement +labels: [enhancement] +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What problem does this feature solve? + placeholder: I need a way to … + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposal + description: What would you like to see? Be specific. + placeholder: Add a flag … / create a script … + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches and why they’re not ideal + - type: textarea + id: additional + attributes: + label: Additional context + description: Links, prior art, screenshots + diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..70934c9 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,24 @@ +Title + +- Use Conventional Commits: type(scope): short summary + - Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert + +Summary + +- What does this change do and why? + +Changes + +- Bullet the key changes +- Reference issues (e.g., Closes #123) + +Testing + +- How did you validate the changes? + +Checklist + +- [ ] Title follows Conventional Commits +- [ ] CI passes (ShellCheck, Yamllint, Actionlint) +- [ ] Docs updated (README/CONTRIBUTING/CHANGELOG as needed) + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e2b6580 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# AGENTS House Rules + +These are persistent, repo-local instructions for AI assistants and automation working in this repository. Follow them in every session. + +## Safety & Workflow +- Never push directly to `main`. Open a PR from a branch. +- Keep PRs small, focused, and well-titled (Conventional Commits). +- Use the PR template. Provide a clear Summary, Changes, and Testing notes. +- Confirm before destructive or sweeping changes; prefer additive or reversible edits. +- Do not modify credentials, tokens, or secrets. Never log secrets. + +## Commits & Releases +- Conventional Commits for titles: `type(scope): summary` (feat, fix, docs, ci, chore, refactor, test, build, perf, revert). +- Update `CHANGELOG.md` as the canonical source for release notes. +- For releases: create short GitHub Release highlights and link to the matching changelog section. +- Use SemVer-lite during 0.x (patch=docs/CI/meta; minor=features; major=breaking). + +## CI & Quality +- Ensure CI passes before merge: ShellCheck, Yamllint, Actionlint. +- Pin or avoid third-party GitHub Actions when possible; prefer native tools (e.g., apt-get install). +- Format shell with `shfmt` (2 spaces, `-i 2 -ci -bn -sr`) and fix ShellCheck findings or justify exceptions inline. + +## Documentation +- Keep README concise: quick start, requirements, revert path, platform notes. +- Use CONTRIBUTING for deeper details (formatting, CI, release process). +- Prefer clarity over cleverness; reflect actual behavior (e.g., PATH-based shfmt vs wrapper). + +## Scope Discipline +- Make only changes explicitly requested or necessary to complete the task. +- If you discover useful adjacent improvements, propose them in the PR description; do not include unless approved. + +## Branch Strategy +- Branch naming: `type/scope/short-description` (e.g., `ci/shellcheck-native`, `docs/readme-badges`). +- Keep linear history; avoid force-push to shared branches. + +## Communication +- Be explicit about assumptions and side effects. +- When uncertain, ask for confirmation with clear options. + +## Local Overrides & Safety +- Respect user-local overrides (e.g., `*.local` files) and avoid clobbering personalized settings. +- For installers or scripts, provide a `--dry-run` option when adding new ones. + +## Examples +- Good PR title: `ci(shellcheck): install and run native shellcheck on ubuntu-latest` +- Good commit title: `docs(readme): clarify shfmt from PATH` + +By following these, assistants and humans can collaborate safely and consistently. From d5ea07d243f5f5fdd6768f4a496021b0b7501e33 Mon Sep 17 00:00:00 2001 From: Ben Rozsa Date: Sun, 14 Sep 2025 21:50:25 +0200 Subject: [PATCH 3/5] docs(agents): tidy formatting per markdownlint --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index e2b6580..2cd0432 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,7 @@ These are persistent, repo-local instructions for AI assistants and automation working in this repository. Follow them in every session. ## Safety & Workflow + - Never push directly to `main`. Open a PR from a branch. - Keep PRs small, focused, and well-titled (Conventional Commits). - Use the PR template. Provide a clear Summary, Changes, and Testing notes. @@ -10,38 +11,46 @@ These are persistent, repo-local instructions for AI assistants and automation w - Do not modify credentials, tokens, or secrets. Never log secrets. ## Commits & Releases + - Conventional Commits for titles: `type(scope): summary` (feat, fix, docs, ci, chore, refactor, test, build, perf, revert). - Update `CHANGELOG.md` as the canonical source for release notes. - For releases: create short GitHub Release highlights and link to the matching changelog section. - Use SemVer-lite during 0.x (patch=docs/CI/meta; minor=features; major=breaking). ## CI & Quality + - Ensure CI passes before merge: ShellCheck, Yamllint, Actionlint. - Pin or avoid third-party GitHub Actions when possible; prefer native tools (e.g., apt-get install). - Format shell with `shfmt` (2 spaces, `-i 2 -ci -bn -sr`) and fix ShellCheck findings or justify exceptions inline. ## Documentation + - Keep README concise: quick start, requirements, revert path, platform notes. - Use CONTRIBUTING for deeper details (formatting, CI, release process). - Prefer clarity over cleverness; reflect actual behavior (e.g., PATH-based shfmt vs wrapper). ## Scope Discipline + - Make only changes explicitly requested or necessary to complete the task. - If you discover useful adjacent improvements, propose them in the PR description; do not include unless approved. ## Branch Strategy + - Branch naming: `type/scope/short-description` (e.g., `ci/shellcheck-native`, `docs/readme-badges`). - Keep linear history; avoid force-push to shared branches. ## Communication + - Be explicit about assumptions and side effects. - When uncertain, ask for confirmation with clear options. ## Local Overrides & Safety + - Respect user-local overrides (e.g., `*.local` files) and avoid clobbering personalized settings. - For installers or scripts, provide a `--dry-run` option when adding new ones. ## Examples + - Good PR title: `ci(shellcheck): install and run native shellcheck on ubuntu-latest` - Good commit title: `docs(readme): clarify shfmt from PATH` From ed0f1b3d7bd0f69261e11140f5abad8eeb82bb68 Mon Sep 17 00:00:00 2001 From: Ben Rozsa Date: Sun, 14 Sep 2025 21:52:39 +0200 Subject: [PATCH 4/5] ci(yamllint): add document start '---' to issue templates --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- .github/ISSUE_TEMPLATE/config.yml | 1 + .github/ISSUE_TEMPLATE/feature_request.yml | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index df3d2c8..6eb91d1 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -1,3 +1,4 @@ +--- name: Bug report description: Report a problem to help us improve labels: [bug] @@ -35,4 +36,3 @@ body: label: Logs / Screenshots description: Paste errors or attach screenshots render: shell - diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index fed5834..6cf7276 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,3 +1,4 @@ +--- blank_issues_enabled: false contact_links: - name: Questions diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml index cd8a61c..ae2bbd5 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.yml +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -1,3 +1,4 @@ +--- name: Feature request description: Suggest an idea or improvement labels: [enhancement] @@ -28,4 +29,3 @@ body: attributes: label: Additional context description: Links, prior art, screenshots - From 3bda771acd1f656127e3d2f95dbcdc3292d9102e Mon Sep 17 00:00:00 2001 From: Ben Rozsa Date: Sun, 14 Sep 2025 21:58:15 +0200 Subject: [PATCH 5/5] ci: retrigger checks