# 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](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](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:**
    ```bash
    cargo test --workspace
    ```
2.  **Lint Check:**
    ```bash
    cargo clippy --workspace --tests -- -D warnings
    ```
3.  **Formatting Check:**
    ```bash
    cargo fmt --check
    ```
4.  **Miri Validation (for core changes):**
    ```bash
    cargo miri test -p justapi-core
    ```
5.  **Run Benchmarks:**
    Run the performance suite and append the new metrics to [BENCHMARKS.md](BENCHMARKS.md). Confirm there is no `p99` latency regression >5% compared to the baseline without a corresponding entry in [DECISIONS.md](DECISIONS.md).
6.  **Roadmap Update:**
    Update the roadmap in [PLAN.md](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.

---

## Resuming Work after Context Reset
If you are an agent resuming work after a context reset:
1.  Read [PLAN.md](PLAN.md) to locate the current phase and its status.
2.  Read the most recent entries in [DECISIONS.md](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](BENCHMARKS.md) to know the performance target.
5.  Continue directly from where the roadmap dictates.