Skip to content

contributing.md

Latest commit

 

History

History
159 lines (116 loc) · 5.52 KB

contributing.md

File metadata and controls

159 lines (116 loc) · 5.52 KB
Raw

CatGo Contributing Guide

Thanks for contributing to CatGo. This guide covers the development setup, the documentation layout, and a few tips for working with AI coding assistants (Claude Code / Cursor / Copilot) on top of the codebase.

1. Development Setup

# 1. Clone the project
git clone https://github.com/Hello-QM/catgo-LRG.git
cd catgo-LRG

# 2. Install JS / pnpm dependencies
pnpm install

# 3. Run the desktop frontend + Python backend together
pnpm desktop:serve            # vite on :3100, FastAPI on :8000

# 4. Or run the Tauri native shell (production frontend + native window)
pnpm tauri:dev                # builds vite then opens the Tauri window

# 5. Backend-only (if you're only working on Python tooling / MCP)
cd server
pip install -r requirements.txt
python main.py                # http://localhost:8000

If you need a fresh checkout to behave like CI, also run:

pnpm exec svelte-kit sync           # regenerates .svelte-kit/tsconfig.json
cd extensions/rust-wasm && pnpm build && cd -   # wasm-pack output (requires Rust)
pnpm run build:doc-chunks           # builds src/lib/chat/docs-chunks.json

2. Repository Layout

The public branch ships the runtime app plus end-user documentation. The top-level surfaces that you'll actually edit:

Path Purpose
src/lib/ Frontend library — Svelte components + TypeScript utilities
desktop/ Tauri webview entry (index.html, App.svelte, etc.)
src-tauri/ Tauri Rust shell (window, IPC, sidecar binaries, app icons)
server/ FastAPI Python backend, MCP server, workflow engine, plugins
extensions/ VSCode extension + Rust-WASM bindings (@catgo/ferrox-wasm)
docs/ VitePress documentation site (guide / modules / tutorials / reference)
tests/vitest/ Frontend unit tests
tests/playwright/ End-to-end browser tests (legacy SvelteKit; currently best-effort)
scripts/ Build helpers — icon generator, doc chunker, backend bundler

3. Tests & Checks

pnpm test                  # vitest run — frontend unit tests
pnpm check                 # svelte-check against ./tsconfig.json

The GitHub Actions Tests workflow (.github/workflows/test.yml) runs the unit suite plus a Playwright job. Both rebuild the gitignored artifacts (.svelte-kit/, extensions/rust-wasm/pkg/, src/lib/chat/docs-chunks.json) before invoking the test runners — replicate those steps locally if your results diverge from CI.

4. Working with AI Coding Assistants

CatGo's codebase is large; AI assistants work best when you tell them exactly which files to look at instead of letting them grep blindly.

Good prompt template

Please read the following files first:
1. <specific path 1>
2. <specific path 2>

Context: <one sentence of background>

Task: <clear action — "add", "fix", "refactor">

Constraints:
- <specific requirement>
- <specific requirement>

Verification: run `pnpm check` and `pnpm test` and report results.

Plan-first workflow

For anything beyond a small fix, ask the assistant to plan first:

Read <relevant files>, then before writing any code, tell me:
1. Which files need to change
2. The proposed approach
3. Risks or things to watch out for

Wait for me to approve before editing.

Where to point the assistant

Goal Files to read first
Project overview readme.md + docs/guide/
Frontend module behaviour The relevant src/lib/<area>/ directory
3D structure viewer internals src/lib/structure/Structure.svelte + src/lib/structure/StructureScene.svelte
Workflow engine src/lib/workflow/ (frontend) + server/catgo/workflow/ (backend)
MCP server / agent tools server/server_claude_code.py + server/catgo/mcp/
Build / bundle pipeline vite.desktop.config.ts, src-tauri/tauri.conf.json, scripts/build-backend.sh
Plugin extensions extensions/ (vscode, rust-wasm, uff-relax, vsepr-rs)

5. Coding Conventions

  • Frontend: Svelte 5 ($state / $derived / $effect), TypeScript strict, ESLint config in eslint.config.js.
  • Backend: Python 3.10+, FastAPI, ruff/black formatting. Tests under server/tests/.
  • Commit style: conventional commits (feat:, fix:, chore:, docs:, test:, ci:).
  • Branching: feature work on a topic branch, PR into main.

6. Getting Help

  • Search existing issues before opening a new one.
  • For larger design discussions, open a GitHub Discussion.
  • The README's "About" section lists the supported quantum chemistry / DFT engines (VASP, ORCA, CP2K, QE, GPAW, DFTB+, SIESTA, LAMMPS) — issues scoped to one engine help reviewers route the work.

Thanks again — happy hacking!

Licensing of contributions

  • Contributors must have the right to submit their work to CatGo.
  • Third-party code must retain its original notices; copying it into CatGo does not relicense third-party code.
  • Accepting a pull request does not by itself prove copyright assignment.
  • Before accepting a contribution, maintainers may require a separate contributor agreement so the project has the right to license and enforce its code.
  • Contributions to CatGo are accepted under AGPL-3.0-or-later.
  • CatGo is licensed under AGPL-3.0-or-later. If CatGo contributes to your work, please include “This work used CatGo (https://app.catgo-ucsd.org).” and the preferred citation in CITATION.cff. This request is not an additional condition of the AGPL license.