Contributing to JustAPI

Welcome! This guide outlines the development workflow, coding standards, and repository conventions for anyone — human or AI — contributing to the JustAPI runtime.

Technical & Architectural Guidelines

Before making any changes, please read ARCHITECTURE.md to understand the crate structure, FFI boundaries, GIL concurrency model, and subsystems.

Repository Conventions

Commit Messages

We follow a structured commit format that links changes to their roadmap phase:

<phase>: <short description>

• Example: p3: add per-request arena allocator
• Rule: Exactly one logical change per commit. Avoid grouping unrelated updates.

Branch Naming

Create feature branches using this prefix style:

phase-N/<short-description>

• Example: phase-42/paged-kv-cache

Code Quality Standards

Memory Safety & unsafe

To maintain the performance boundary without introducing memory safety hazards:

• Every unsafe block MUST be accompanied by a // SAFETY: comment explaining the specific invariant that makes the block sound.
• Whenever feasible, add a test that would trigger Miri or cause a panic if that invariant were violated.

Dependency Management

• Do not add new dependencies lightly.
• Every new dependency MUST be justified in DECISIONS.md detailing what it replaces or enables, and why alternative approaches (like writing the logic yourself) are inferior.

Public API Changes

• Any changes to public Rust APIs or public Python functions/decorators MUST include complete documentation (rustdoc or Python docstrings) before the pull request is marked as ready for review.

Error Handling

• Application Code (CLI, Benchmarks): Use anyhow::Result for generic context-wrapping errors.
• Library Crates (justapi-core, justapi-py): Use typed errors (thiserror) for any error crossing crate or FFI boundaries to guarantee type safety and clear error messages.

Pre-Submission Checklist

Before submitting a Pull Request, verify that all of the following steps pass:

1. Run Workspace Tests:

   cargo test --workspace
   

2. Lint Check:

   cargo clippy --workspace --tests -- -D warnings
   

3. Formatting Check:

   cargo fmt --check
   

4. Miri Validation (for core changes):

   cargo miri test -p justapi-core
   

5. Run Benchmarks:
   Run the performance suite and append the new metrics to BENCHMARKS.md. Confirm there is no p99 latency regression >5% compared to the baseline without a corresponding entry in DECISIONS.md.
6. Roadmap Update:
   Update the roadmap in PLAN.md to reflect the status of active or completed phases.
7. Pattern/Skill Documentation:
   If you discover a recurring pattern or gotcha, document it by updating or creating a SKILL.md under the skills/ directory.

Versioning & Deprecation Policy

Semantic Versioning

JustAPI follows Semantic Versioning 2.0.0:

• Major (X.0.0): Breaking changes to public API. Requires migration guide.
• Minor (0.X.0): New features, backward-compatible. May deprecate existing APIs.
• Patch (0.0.X): Bug fixes, backward-compatible. No API changes.

Current status: Pre-1.0. Minor versions may contain breaking changes (documented in CHANGELOG.md with migration notes).

Deprecation Process

When a public API is deprecated:

1. Add #[deprecated(since = "X.Y.Z", note = "use new_api() instead")] (Rust) or warnings.warn(...) (Python)
2. Document the deprecation in CHANGELOG.md under ### Deprecated
3. Provide a migration example in the deprecation note
4. Remove the deprecated API in the next minor version (not patch)

Breaking Change Requirements

Before merging a breaking change:

• CHANGELOG.md updated with ### Changed or ### Removed entry
• Migration guide written (new section in docs or inline in CHANGELOG)
• Deprecation period of at least one minor version (unless critical security fix)
• All downstream examples and tests updated

Resuming Work after Context Reset

If you are an agent resuming work after a context reset:

1. Read PLAN.md to locate the current phase and its status.
2. Read the most recent entries in DECISIONS.md to understand why recent architecture decisions were made.
3. Skim any relevant SKILL.md files in the area of the codebase you are modifying.
4. Check the last recorded numbers in BENCHMARKS.md to know the performance target.
5. Continue directly from where the roadmap dictates.