Skip to content

[Docs]: Add shellcheck guidance to CONTRIBUTING.md #155

@sjnims

Description

@sjnims

Which documentation needs improvement?

  • Contributing guidelines

Specific Location

CONTRIBUTING.md - Add new section on shell script quality

What's unclear or missing?

The plugin contains numerous shell scripts but there's no documented guidance on:

  • Running shellcheck before submitting PRs
  • Expected shellcheck compliance level
  • How to handle intentional patterns that trigger warnings

Suggested Improvement

Add a "Shell Script Quality" section to CONTRIBUTING.md:

## Shell Script Quality

All shell scripts should pass shellcheck validation. Run before submitting:

\`\`\`bash
# Check all plugin scripts
shellcheck plugins/plugin-dev/skills/*/scripts/*.sh

# Check specific script
shellcheck plugins/plugin-dev/skills/hook-development/scripts/test-hook.sh
\`\`\`

### Handling Intentional Patterns

If a pattern intentionally triggers a shellcheck warning, add a directive comment:

\`\`\`bash
# shellcheck disable=SC2086  # Word splitting intended here
command $unquoted_var
\`\`\`

Always include a comment explaining why the directive is needed.

### Common Issues

| Warning | Typical Fix |
|---------|-------------|
| SC2086 | Quote variables: "$var" |
| SC2046 | Quote command substitution: "$(cmd)" |
| SC2034 | Remove unused variables or export them |

Type of issue

  • Missing information

Additional Context

CLAUDE.md already mentions shellcheck plugins/plugin-dev/skills/*/scripts/*.sh in the Linting section, but CONTRIBUTING.md doesn't reference this or explain expectations for contributors.

Consider also:

  • Adding shellcheck to CI (component-validation.yml)
  • Creating a pre-commit hook for local validation

Metadata

Metadata

Assignees

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions