Contribution Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• README.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• crates/arbor-cli/src/commands.rs
• crates/arbor-core/src/parser_v2.rs

Arbor is an open-source, local-first impact analysis engine that parses codebases into semantic dependency graphs. These guidelines outline the technical and behavioral standards for contributors to ensure the project remains robust, performant, and maintainable. The project welcomes contributions ranging from bug fixes and new language parsers to performance optimizations and visualizer enhancements.

Sources: CONTRIBUTING.md:1-20, README.md:20-35

Getting Started and Environment Setup

Contributors must prepare a development environment that supports both the Rust-based backend and the Flutter-based visualizer. The project requires Rust (1.70+) and Flutter (3.0+) for core development.

Development Prerequisites

Tool	Minimum Version	Purpose
Rust	1.70	Backend crates and CLI development
Flutter	3.0	Visualizer (GUI) development
Node.js	N/A	Testing TypeScript parsing logic

Sources: CONTRIBUTING.md:38-46

Standard Build Workflow

The following sequence should be used to initialize the development environment:

1. Clone: `git clone https://github.com/Anandb71/arbor.git%60
2. Build Backend: Navigate to crates/ and execute cargo build.
3. Verify: Run cargo test --all to ensure the baseline is stable.
4. GUI Setup: Navigate to visualizer/, run flutter pub get, and flutter build [platform].

Sources: CONTRIBUTING.md:48-65

Development Workflow and Standards

Arbor follows a structured workflow for making changes, emphasizing descriptive naming and strict adherence to conventional commit standards.

Branching and Commits

Contributors should use the following branch prefixes:

• feat/: New features (e.g., feat/python-parser)
• fix/: Bug fixes (e.g., fix/watcher-memory-leak)
• docs/: Documentation updates
• refactor/: Code cleanups

Commit messages must follow conventional commits to maintain a readable history, such as feat(core): add Python class inheritance tracking.

Sources: CONTRIBUTING.md:83-102

Code Quality and Linting

The project enforces strict linting and formatting rules for both Rust and Flutter codebases to ensure consistency.

The diagram shows the validation pipeline required before submitting changes.
Sources: CONTRIBUTING.md:104-111, CONTRIBUTING.md:154-170

Technical Implementation Guidelines

Adding Language Support

Arbor uses Tree-sitter for its multi-language parsing engine. Adding support for a new language involves five primary steps:

1. Grammar Integration: Add the relevant tree-sitter-[lang] dependency in crates/arbor-core/Cargo.toml.
2. Module Creation: Create a new language module in crates/arbor-core/src/languages/.
3. Parser Implementation: Implement the LanguageParser trait, defining extensions and node extraction logic.
4. Registry Update: Register the new parser in the central language module.
5. Validation: Add comprehensive test cases in crates/arbor-core/tests/.

Sources: CONTRIBUTING.md:121-152, crates/arbor-core/src/parser_v2.rs:100-140

Parser Architecture (v2)

The ArborParser utilizes pre-compiled queries for high performance across large codebases. It is designed for incremental updates, ensuring that existing nodes are updated rather than duplicated.

The flow illustrates how ArborParser processes source files into symbols and relationships.
Sources: crates/arbor-core/src/parser_v2.rs:1-30, crates/arbor-core/src/parser_v2.rs:142-180

Pull Request and Review Process

All contributions must be submitted via Pull Requests (PRs) from a forked repository.

1. Prerequisites: PRs must pass all local tests and clippy lints.
2. Template: Contributors must fill out the provided PR template, which helps maintainers review changes faster.
3. Documentation: If a change alters behavior, corresponding documentation in README.md or CHANGELOG.md must be updated.
4. Review: Maintainers typically review PRs within a few days; complex architectural changes may take longer.

Sources: CONTRIBUTING.md:113-119

Security and Community Standards

Security Policy

Vulnerabilities should never be reported via public GitHub issues. Instead, security concerns must be emailed to the maintainers at <anandbiju71@gmail.com>. The project aims to respond within 48 hours and fix critical issues within 7 days.

Sources: SECURITY.md:1-25

Code of Conduct

All participants are expected to uphold the Contributor Covenant. This includes:

• Using welcoming and inclusive language.
• Being respectful of differing viewpoints.
• Gracefully accepting constructive criticism.
• Avoiding harassment, trolling, and personal attacks.

Sources: CODE_OF_CONDUCT.md:1-25

Summary

Contributors are the backbone of the Arbor project. By adhering to the standardized Rust and Flutter development workflows, implementing robust Tree-sitter parsers, and following the security and community standards, you help build a deterministic and explainable impact analysis engine. Always ensure that the cargo run -- check-health command passes before submitting your work to verify your local environment configuration.

Sources: CONTRIBUTING.md:65, crates/arbor-cli/src/commands.rs:442-450