Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (73 loc) · 3.4 KB

CONTRIBUTING.md

File metadata and controls

105 lines (73 loc) · 3.4 KB

Contributing to skillscan-security

Thank you for contributing. This document covers the development workflow, CI requirements, and the branch protection settings that enforce them.

Development workflow

All changes — including those from automated agents — go through a pull request. Direct pushes to main are blocked by branch protection rules.

# 1. Create a feature or fix branch
git checkout -b fix/describe-the-change

# 2. Make changes, then verify locally before pushing
ruff check .
ruff format --check .
mypy src/skillscan/
pytest tests/ -q

# 3. Push and open a PR
git push origin fix/describe-the-change
gh pr create --fill

# 4. CI runs automatically on the PR
# 5. All checks must be green before merging

CI checks

Every PR must pass all of the following before it can be merged:

Check Command What it enforces
Lint ruff check . No unused imports, undefined names, or style violations
Format ruff format --check . Consistent code style (equivalent to black)
Type check mypy src/skillscan/ No type annotation errors
Tests pytest tests/ -q All unit and integration tests pass

Run all four locally before pushing:

ruff check . && ruff format --check . && mypy src/skillscan/ && pytest tests/ -q

Branch protection settings

The following settings are configured on main in GitHub → Settings → Branches → Branch protection rules:

Setting Value Why
Require a pull request before merging ✅ Enabled Prevents direct pushes to main
Required status checks test (3.11), test (3.12), Lint & format CI must be green before merge
Require branches to be up to date before merging ✅ Enabled Prevents stale-branch merges that pass CI but break main
Do not allow bypassing the above settings ✅ Enabled Applies to admins and bots too
Allow force pushes ❌ Disabled Preserves commit history
Allow deletions ❌ Disabled Prevents accidental main deletion

To configure these settings yourself:

  1. Go to https://github.com/kurtpayne/skillscan-security/settings/branches
  2. Click Add branch protection rule (or edit the existing main rule)
  3. Set Branch name pattern to main
  4. Enable the settings in the table above
  5. Under Require status checks to pass before merging, search for and select: test (3.11), test (3.12), Lint & format
  6. Click Save changes

Commit message format

Use Conventional Commits:

<type>: <short description>

<optional body>

Common types: feat, fix, docs, refactor, test, chore.

Examples:

  • feat: add temporal trigger detection rule (MAL-055)
  • fix: resolve mypy no-any-return in skill_schema
  • docs: update CONTRIBUTING with branch protection steps

Adding new detection rules

  1. Add the rule entry to src/skillscan/data/rules/default.yaml inside static_rules
  2. Include a test_input: | block with sample content that triggers the rule
  3. Include test_expect: fires after the test_input
  4. Run python3 scripts/sync-website-rules.py to update the website TSX files
  5. Run SKILLSCAN_NO_USER_RULES=1 pytest tests/test_rule_inputs.py -q to verify
  6. Open a PR — CI will validate the YAML parses and the rule fires on its test_input

Questions

Open an issue or start a discussion on GitHub.