Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
92 lines (67 loc) · 3.29 KB

CONTRIBUTING.md

File metadata and controls

92 lines (67 loc) · 3.29 KB
Raw

Contributing

Thanks for your interest in improving claude-nfcore-docs.

Quick start

# Clone and install
git clone https://github.com/benjibromberg/claude-nfcore-docs.git
cd claude-nfcore-docs

# Install the skill locally (links to your working copy)
mkdir -p ~/.claude/skills/nfcore-docs
ln -sf "$(pwd)/SKILL.md" ~/.claude/skills/nfcore-docs/SKILL.md

# Set up the docs cache (if not already done)
# The skill auto-creates this on first use, but you can do it manually:
mkdir -p ~/.cache/nfcore-docs && cd ~/.cache/nfcore-docs
git init && git remote add origin https://github.com/nf-core/website.git
git config core.sparseCheckout true
printf 'sites/docs/src/content/docs/\nsites/docs/src/content/api_reference/\n' > .git/info/sparse-checkout
git pull origin main --depth 1

Now edit SKILL.md, invoke /nfcore-docs in any Claude Code session, and your changes are live immediately.

Testing

56 tests in TESTS.md. Each has a copy-paste prompt for manual testing.

# In a Claude Code session from an nf-core pipeline directory:
Read /path/to/claude-nfcore-docs/TESTS.md and run Test N

Run the full test suite by working through all 56 tests. Priority tests for quick validation: 1 (freshness), 10 (full audit), 11 (interactive menu), 18 (NEVER rules), 43 (dependencies).

What to contribute

  • Bug fixes — skill produces wrong output, crashes, or violates its own NEVER rules
  • Guardrail improvements — better prompting that reduces hallucination or error
  • Test cases — new tests for untested scenarios or edge cases
  • nf-core spec coverage — the skill should stay current with nf-core spec changes
  • Documentation — README, TESTS.md, or CLAUDE.md improvements

Key constraints

Read the CLAUDE.md for full constraints. The critical ones:

  • No hardcoded spec content — derive everything from cached doc files at runtime
  • NEVER summarize agent results — present all findings verbatim
  • NEVER truncate command output — no head/tail/grep on diagnostics
  • Delegate to nf-core tools — never reimplement lint, create, schema build, etc.
  • Keep the installed copy in sync — if you edit SKILL.md, the installed copy at ~/.claude/skills/nfcore-docs/SKILL.md must match

Linting & pre-commit

All Python code must pass ruff lint and format checks. Configuration is in pyproject.toml (excludes fixture pipelines).

Set up pre-commit hooks to enforce this automatically on every commit:

pip install pre-commit   # if not already installed
pre-commit install       # installs git hooks

After this, every git commit will automatically run ruff lint, ruff format, trailing whitespace checks, and YAML/JSON validation. If any hook fails, the commit is blocked until you fix the issue.

# Run all hooks manually (without committing)
pre-commit run --all-files

# Or run ruff directly
ruff check tests/ && ruff format --check tests/

CI also enforces ruff via astral-sh/ruff-action@v3 — PRs will fail if ruff reports any issues.

Pull requests

  • One feature or fix per PR
  • Run ruff check and ruff format before pushing
  • Update TESTS.md if adding testable behavior
  • Update CLAUDE.md if changing constraints or architecture
  • Test your changes by actually using /nfcore-docs in a real session