​

Contributing Guide

We welcome—and rely on—community contributions. This guide outlines the development workflow, style conventions, and review process.

​

1. Issue Tracker

• Bug Report – Provide reproduction steps and stack traces. Attach sample Parquet if relevant.
• Feature Request – Describe the use-case, not just the solution. Explain why existing workflows are insufficient.

Labels:

​

2. Development Environment

Follow the Installation Guide (source checkout path). Clone your fork and create a topic branch:

git checkout -b feat/my-improvement

Run both servers in watch mode:

(cd backend && uvicorn main:app --reload --port 8001)
(cd frontend && npm run dev)

​

3. Coding Standards

​

3.1 Python

• Formatter: Black (line length 88). Run uv pip install black if needed.
• Linter: Ruff – CI fails if ruff --quiet reports issues.
• Type Hints: Use typing.Literal, Path, etc. MyPy is optional but appreciated.

​

3.2 TypeScript / Svelte

• Prettier: auto-formated on commit.
• ESLint: Config in frontend/eslint.config.js.
• Component files should stay under 300 lines unless unavoidable.

​

4. Commit Messages

<type>(scope): short summary

Body explaining *what* and *why* (not *how*). Reference issues.

Examples:

feat(frontend): add theme switcher (#42)
fix(backend): handle empty DataFrame edge-case (#55)

​

5. Testing

• Backend unit tests should live under backend/tests/ (PyTest).
• Front-end unit tests (Vitest) under frontend/src/lib/__tests__/.
• Use “Golden Files” for serialization outputs where appropriate.

CI runs via GitHub Actions. Push to your branch; the pipeline must turn green before review.

​

6. Documentation

All user-facing changes require corresponding docs updates under docs/ (this site). We use MDX; code blocks auto-highlight via Prism.

​

7. Pull Request Lifecycle

1. Draft PR against main.
2. At least one core maintainer review.
3. Squash-merge using GitHub UI.
4. Release notes updated in CHANGELOG.md (maintainers will handle if you include a # Changelog section in PR description).

​

8. Code of Conduct

Be respectful and constructive. We follow the Contributor Covenant v2.1.

​

9. Community

• Discussions Tab – Propose ideas or ask usage questions.
• Matrix/Slack – Coming soon. Suggest your preference in an issue.

​

Thank You

Every merged PR is credited in the release notes. Your name, handle, or corporate affiliation will appear unless you opt out.