Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
140 lines (103 loc) · 2.95 KB

CONTRIBUTING.md

File metadata and controls

140 lines (103 loc) · 2.95 KB

Contributing to FlowScope

Thank you for your interest in contributing to FlowScope! This document provides guidelines and instructions for setting up your development environment and contributing to the project.

Development Setup

Prerequisites

  • Rust (latest stable) - Install via rustup
  • Node.js >= 18.0.0
  • Yarn >= 1.22.0
  • wasm-pack - Install via cargo install wasm-pack

Initial Setup

  1. Clone the repository:
git clone https://github.com/pondpilot/flowscope.git
cd flowscope
  1. Install dependencies:
yarn install
  1. Build the project:
just build
  1. Run tests:
just test

Project Structure

FlowScope is organized as a monorepo with the following structure:

  • crates/ - Rust workspace
    • flowscope-core/ - Core lineage engine
    • flowscope-wasm/ - WASM bindings
    • flowscope-cli/ - CLI wrapper
    • flowscope-export/ - Export helpers
  • packages/ - NPM workspace
    • core/ - TypeScript wrapper (@pondpilot/flowscope-core)
    • react/ - React components (@pondpilot/flowscope-react)
  • app/ - Demo Vite application
  • vscode/ - VS Code extension + webview UI
  • docs/ - Documentation

Development Workflow

Making Changes

  1. Create a new branch:
git checkout -b feature/your-feature-name
  1. Make your changes
  2. Run tests:
just test
  1. Run linters:
just check
  1. Format code:
just fmt
  1. Keep docs in sync:
# See docs/README.md for canonical references.

Running the Demo

just dev

Code Style

Rust

  • Follow standard Rust conventions
  • Run cargo fmt before committing
  • Run cargo clippy and address warnings

TypeScript

  • Use strict TypeScript
  • Single quotes for strings
  • Trailing commas in multiline structures
  • Run just fmt before committing

Code Generation

  • Dialect semantic specs in crates/flowscope-core/specs/dialect-semantics/ are compiled into crates/flowscope-core/src/generated/ by build.rs.
  • API schema snapshots live in docs/api_schema.json and can be refreshed with just update-schema.

Testing

  • Write unit tests for all new functionality
  • Ensure all tests pass before submitting a PR
  • Add integration tests for complex features
  • Test fixtures should be added to crates/flowscope-core/tests/fixtures/

Pull Request Process

  1. Update documentation for any new features
  2. Add tests for your changes
  3. Ensure all tests pass
  4. Update CHANGELOG.md if applicable
  5. Submit PR with a clear description of changes
  6. Address review feedback

Reporting Issues

When reporting issues, please include:

  • FlowScope version
  • Operating system
  • Node.js and Rust versions
  • Steps to reproduce
  • Expected vs actual behavior
  • Any error messages or logs

License

By contributing to FlowScope, you agree that your contributions will be licensed under the Apache 2.0 License.

Questions?

Feel free to open an issue for questions or join our discussions!