Skip to content

Commit 444ed21

Browse files
sjnimsclaude
andauthored
docs: add shellcheck guidance to CONTRIBUTING.md (#160)
## Description Add "Shell Script Quality" section to CONTRIBUTING.md documenting shellcheck requirements and best practices for contributors. ## Type of Change - [x] Documentation update (improvements to README, CLAUDE.md, or component docs) ## Component(s) Affected - [x] Documentation (README.md, CLAUDE.md, SECURITY.md) ## Motivation and Context The plugin contains numerous shell scripts but there was no documented guidance for contributors on: - Running shellcheck before submitting PRs - Expected shellcheck compliance level - How to handle intentional patterns that trigger warnings CLAUDE.md mentions shellcheck in the Linting section, but CONTRIBUTING.md didn't reference this or explain expectations. Fixes #155 ## Solution Added "Shell Script Quality" subsection under Development Guidelines with: - Commands to run shellcheck on plugin scripts - How to add `# shellcheck disable=SCXXXX` directives for intentional patterns - Common issues table (SC2086, SC2046, SC2034, SC2155) ## Changes - `CONTRIBUTING.md`: Added new "Shell Script Quality" section ## Testing - [x] Linting passes (markdownlint) --- 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
1 parent 873a6ce commit 444ed21

1 file changed

Lines changed: 32 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,38 @@ Current branch: [BANG]`git branch --show-current`
167167
- Command files (`.claude/commands/*.md`) use actual `!` syntax
168168
- See [SECURITY.md](SECURITY.md#shell-pattern-escaping-with-bang-placeholder) for full details
169169

170+
### Shell Script Quality
171+
172+
All shell scripts should pass [shellcheck](https://www.shellcheck.net/) validation:
173+
174+
```bash
175+
# Check all plugin scripts
176+
shellcheck plugins/plugin-dev/skills/*/scripts/*.sh
177+
178+
# Check a specific script
179+
shellcheck plugins/plugin-dev/skills/hook-development/scripts/test-hook.sh
180+
```
181+
182+
#### Handling Intentional Patterns
183+
184+
If a pattern intentionally triggers a shellcheck warning, add a directive comment:
185+
186+
```bash
187+
# shellcheck disable=SC2086 # Word splitting intended for arguments
188+
command $unquoted_var
189+
```
190+
191+
Always include a comment explaining why the directive is needed.
192+
193+
#### Common Issues
194+
195+
| Warning | Typical Fix |
196+
|---------|-------------|
197+
| SC2086 | Quote variables: `"$var"` |
198+
| SC2046 | Quote command substitution: `"$(cmd)"` |
199+
| SC2034 | Remove unused variables or export them |
200+
| SC2155 | Separate declaration and assignment: `local var; var=$(cmd)` |
201+
170202
## Component-Specific Guidelines
171203

172204
### Commands (`/plugin-dev:*`)

0 commit comments

Comments
 (0)