Skip to content

Contributing

Jump to bottom
Paige Quarterman edited this page May 3, 2026 · 1 revision

Contributing

This is a personal research tool, but bug reports and pull requests are welcome.

Branch conventions

  • feat/<short-name> — new feature
  • fix/<short-name> — bug fix
  • refactor/<short-name> — internal change without user-visible behavior
  • docs/<short-name> — documentation only
  • chore/<short-name> — tooling, CI, dependencies

Never commit directly to main from a feature change. The maintainer often runs multiple Claude Code sessions in parallel; direct-to-main causes dirty-tree errors and lost changes. Workflow:

git checkout -b feat/my-thing
# ...edit, test...
git commit -m "feat(scope): short description"
git checkout main
git merge feat/my-thing --no-edit
git branch -d feat/my-thing

Documentation-only changes and single-line typo fixes can go directly to main.

Commit messages

Conventional Commits:

<type>(<scope>): <description>

Types: feat, fix, refactor, docs, test, chore, style, perf. Scope is optional but encouraged (parser, cli, ui/database, config). Description is imperative mood, lowercase, no period, ≤72 chars.

Examples:

  • feat(parser): add Bruker XYE import
  • fix(scraper): activeSources now rebuilds after bridge ready
  • docs: distinguish domain config from user reference data

Multi-line messages: blank line, then explain why, not what. The diff already shows what.

Test expectations

Run the full suite before committing:

pytest                  # 325 specs
npm test                # 595 specs
npm run typecheck       # tsc --noEmit on @ts-check files

Adding code without adding tests will get pushback. The minimum bar:

  • New service / config helper / CLI subcommand → unit tests.
  • New shared behavior between JS and Python → a vector in tests/vectors/<category>/.
  • New UI module → a story in src/dev/stories/ (testable by hand) plus a vitest spec for any pure logic it contains.
  • New endpoint in scq/server.py → a fixture-based pytest using the existing running_server pattern in tests/test_serve_*.py.

Bug fixes get regression tests in the same commit. The bug-hunter agent has caught several "tests would have caught this" cases — write the test first, watch it fail, then fix.

Documentation discipline

Three rules:

  1. Update docs in the same commit as code. No "I'll update the README later" — that's how documentation rots. The tests/test_doc_drift.py catcher fails CI if a retired symbol shows up in active doc text.
  2. Don't write what the code already says. Documentation should explain why a thing exists or how to use it from outside. If you're describing what the code does line by line, you're writing the wrong thing. The code already does that.
  3. In-tree docs vs. wiki. In-tree (docs/, CLAUDE.md, README.md) tracks code paths and evolves with the codebase. Wiki is for project-level guidance that doesn't reference specific files. If you find yourself wanting to write docs/<file>.md that names no specific code path, put it in the wiki.

Tooling agents

The maintainer often delegates work to specialized agents (bug-hunter, code-architect, etc.) under Claude Code. If you're a contributor running Claude Code:

  • .claude/skills/ has four project-specific skills: add-paper, enrich-paper, db-maintenance, literature-review. They contain the exact code patterns the maintainer uses.
  • CLAUDE.md is the per-project orientation document. Read it once.
  • The maintainer has global rules in ~/.claude/ (branch-before-implement, commit-message format, plan-hygiene) — these are referenced from CLAUDE.md and apply project-wide.

Releases

There are no formal releases yet. Production = main. The repo is single-user; the GitHub Pages demo deploys on push to main via .github/workflows/pages.yml.

If formal releases get wanted later: add a changelog (Keep a Changelog format), tag versions, and use .github/workflows/release.yml to publish artifacts. Until then, git log is the changelog.

Reporting issues

  • Security issues: see SECURITY.md. The repo has Private Vulnerability Reporting enabled — use that, not a public issue.
  • Bugs: open a GitHub issue with reproduction steps. Include the output of scq config show (with secrets redacted) and scq config validate if relevant.
  • Feature requests: also a GitHub issue, but understand the maintainer is unlikely to take large requests for a personal-research tool. Forks are welcome.

Code of conduct

Contributor Covenant 2.1. See CODE_OF_CONDUCT.md.

Clone this wiki locally