Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
162 lines (112 loc) · 4.87 KB

CONTRIBUTING.md

File metadata and controls

162 lines (112 loc) · 4.87 KB

Contributing to NeuronPrompter

Thank you for your interest in contributing to NeuronPrompter. This document describes the process for contributing code, reporting bugs, and working with the codebase.

Please read and follow the Code of Conduct in all interactions with the project.

Before You Contribute

NeuronPrompter maintains a high standard for code quality, architecture, and consistency. All contributions are welcome -- no prior introduction is required.

For small changes (typos, documentation, bug fixes with clear scope): open a pull request directly. The PR template and CI pipeline guide you through the quality checks.

For larger changes (new features, architectural modifications, new crates): open a GitHub Discussion or Issue first to align on the approach before writing code. This avoids wasted effort on changes that may conflict with the project's direction.

Bug reports and feature requests do not require prior discussion -- use the issue templates directly.

Development Setup

For architecture details and crate boundaries, see docs/architecture/architecture.pdf.

Prerequisites

  • Rust 1.88+ (stable) -- install via rustup
  • Node 22+ and npm -- for the SolidJS frontend build
  • Git -- for version control and pre-commit hooks
  • Linux only (Debian/Ubuntu): sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libayatana-appindicator3-dev librsvg2-dev

Clone and Build

git clone https://github.com/FF-TEC/NeuronPrompter.git
cd NeuronPrompter

# Build the SolidJS frontend (required for the web feature)
cd crates/neuronprompter-web/frontend && npm ci && npm run build && cd ../../..

# Build the Rust binary with all default features
cargo build -p neuronprompter

Feature Flags

The binary crate has three feature flags, all enabled by default:

Flag Purpose
web SolidJS frontend embedded via rust-embed
gui Native window via tao/wry (requires web)
mcp Model Context Protocol server for Claude Code and Claude Desktop App

For a headless server build without native GUI:

cargo build -p neuronprompter --no-default-features \
  --features web,mcp

Frontend Development

During frontend development, run the Vite dev server and the Rust backend separately:

# Terminal 1: Start the Rust backend
cargo run -p neuronprompter -- serve --port 3030

# Terminal 2: Start the Vite dev server (proxies /api/v1 to port 3030)
cd crates/neuronprompter-web/frontend
npm run dev

Code Style

Rust

  • Formatter: cargo fmt (config in rustfmt.toml: 4 spaces, max width 100)
  • Linter: cargo clippy with workspace-wide lint configuration
  • Comments: English, describing the current state of the code (not aspirations or history). No exaggerations ("ultra", "enhanced", "optimized"), no emojis.
  • Error handling: thiserror in library crates, anyhow in the binary crate. Use expect("reason") instead of bare unwrap().
  • Unsafe code: Forbidden in all crates (#![forbid(unsafe_code)] where applicable)

TypeScript / Frontend

  • Linting: ESLint (no dedicated formatter configured)
  • Framework: SolidJS with TypeScript
  • Styles: CSS custom properties defined in crates/neuronprompter-web/frontend/src/styles/variables.css

Testing

Run the full test suite before submitting a pull request:

cargo test --workspace

The repository includes pre-commit hooks that run automatically on each commit. Configure git to use the tracked hooks directory:

git config core.hooksPath .githooks

The hooks check: formatting (cargo fmt), linting (cargo clippy), license compliance (cargo deny), and tests (cargo test).

CI must pass on all target platforms before a pull request is merged.

Pull Request Process

  1. Fork the repository and create a feature branch from master.
  2. Write a descriptive branch name (e.g., fix-search-pagination, add-csv-export).
  3. Keep commits focused -- one logical change per commit.
  4. Ensure cargo fmt, cargo clippy, and cargo test pass locally.
  5. Open a pull request with a clear title and description. Reference related issues if applicable.
  6. The maintainer reviews the PR. Address feedback in additional commits (do not force-push during review).
  7. Once approved, the maintainer merges the PR.

Reporting Bugs

Use the Bug Report issue template. Include:

  • Steps to reproduce
  • Expected vs. actual behavior
  • Environment details (OS, NeuronPrompter version, enabled features)
  • Relevant log output

License

By contributing to NeuronPrompter, you agree that your contributions are licensed under the MIT OR Apache-2.0 license. No Contributor License Agreement (CLA) is required.