CONTRIBUTING.md

Contributing to VaultSync

Thank you for your interest in contributing to VaultSync! We welcome issues, feature requests, and pull requests from everyone.

---

📋 Prerequisites

Before setting up your workspace, ensure you have the following installed:

• Rust 1.75+ (rustup install stable)
• Node.js 18+ (NPM v9+)
• wasm-pack (cargo install wasm-pack)
• Docker (required for running coordinator tests locally)

---

🚀 Getting Started

1. Fork the repository on GitHub.
2. Clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/vaultsync.git
   cd vaultsync

3. Run the developer environment setup script:

   ./scripts/setup-dev.sh

   This script initializes dependencies, compiles NAPI/WASM files, and sets up configurations.

---

📂 Project Structure

• crates/vaultsync-core/ — Core Rust sync engine
• crates/vaultsync-wasm/ — WASM browser bindings
• crates/vaultsync-napi/ — Node-API native bindings
• crates/vaultsync-coordinator-*/ — Coordinator protocol implementations
• crates/vaultsync-cli/ — Command-line tools
• sdk/packages/ — TypeScript/React SDK packages (web, node, react, next)
• sdk/examples/ — Ready-to-run demo apps
• docs/ — Specifications

---

🎨 Coding Standards

Linting & Formatting

We enforce strict linting and formatting gates in CI:

• Rust:

  cargo fmt --check
  cargo clippy --workspace --all-targets -- -D warnings

• TypeScript / JavaScript:

  npm run lint --prefix sdk
  npm run format:check --prefix sdk

Please run these commands locally before opening a pull request.

Commit Conventions

We follow the Conventional Commits format:

<type>(<scope>): <description>

[optional body]

Common Types:

• feat: A new user-facing feature.
• fix: A bug fix.
• docs: Changes to documentation or specifications.
• style: Code style tweaks (whitespace, formatting, etc.).
• refactor: Code change that neither fixes a bug nor adds a feature.
• test: Adding or correcting tests.
• chore: Internal build/infra adjustments.

---

🧪 Testing Checklist

Before opening a PR, ensure all tests pass cleanly:

# Run unit, integration, chaos, and E2E tests across all platforms
./scripts/run-all-tests.sh

If you introduce a new feature, you are expected to include corresponding unit or integration tests verifying the behavior.

---

📥 Pull Request Workflow

1. Create a branch for your feature or fix:

   git checkout -b feat/your-awesome-feature

2. Commit your changes following the Commit Conventions.
3. Push your branch to your fork:

   git push origin feat/your-awesome-feature

4. Open a Pull Request against the main branch of the official VaultSync repository.
5. Wait for the automated CI suite to run and pass.
6. A maintainer will review your pull request shortly!

---

📄 License

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