diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..6eb91d1 --- /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..6cf7276 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,6 @@ +--- +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..ae2bbd5 --- /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/.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[@]}" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2cd0432 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,57 @@ +# 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.