AstrAI/CONTRIBUTING.md

Contributing to AstrAI

Thank you for your interest in contributing! This document provides step-by-step guidelines.

Quick Start

git clone https://github.com/ViperEkura/AstrAI.git
cd AstrAI
pip install -e ".[dev]"     # install with dev dependencies (pytest, ruff)

Before You Commit

Run the following checks in order — CI will reject if any fail.

1. Format

ruff format .

2. Import sorting

ruff check . --select I

If this fails, manually fix import ordering (ruff does not auto-fix in this project's CI):

ruff check . --select I --fix .
ruff format .    # re-format after fix

3. Run tests

python -u -m pytest tests/ -v

Failed tests may leave orphan tempdirs under the system temp directory ($TMPDIR on Linux/macOS, %TEMP% on Windows). Clean them manually if needed.

4. (Optional) Full pre-commit check script

If you have bash available (Git Bash on Windows works too):

bash scripts/pre_commit.sh

The script installs development dependencies by default, then runs the format check, import sort check, and tests. If dependencies are already installed, use:

bash scripts/pre_commit.sh --skip-deps

Commit Style

type: short description (~50 chars)

- bullet point body (each ~60 chars)

• Type must be one of: fix, feat, chore, docs, refactor, perf, test, style, ci, build, revert.
• Subject line ends with no period.
• Body uses bullet points starting with -, one bullet per line, no wrapping.
• No (scope) parentheses.
• Performance-affecting changes (perf, and refactor/feat that move numbers) must add a Benchmark: section: one line stating the environment (GPU, dtype, model, relevant switches, measurement method), then one - bullet per data point in the form old -> new unit (ratio, +-%).

Example: regular commit

fix: keep async rollouts version-consistent

- serialize shared-model optimizer updates with generation
- reject future or over-lagged rollout results after asynchronous scoring
- close cache publication races
- persist policy versions in online checkpoints

Example: performance commit with Benchmark section

refactor: standardize packed 3d inference

- keep training attention on dense 4d tensors
- use packed 3d tensors with KV cache for inference
- extend CUDA rotary embedding to packed 3d inputs
- adapt torch, CUDA and FlashAttention backend dispatch

Benchmark: NVIDIA L20, BF16, 1B model, paged KV cache, CUDA Graph, prompt 512, generation 128 (median of 3 alternating runs)
- batch 1: 234.5 -> 242.6 tok/s (1.034x, +3.4%)
- batch 8: 1243.1 -> 1286.6 tok/s (1.035x, +3.5%)

Both examples are real commits from this repository (git show them to verify formatting).

Common Issues

Problem	Cause	Fix
ruff check --select I fails	Wrong import order	ruff check . --select I --fix . then ruff format .
ruff format changed many files	Not formatted before commit	Review diff carefully before staging
Pre-commit check script fails	Dependency install, tests, or lint failed	Fix the failing step; use --skip-deps only when dependencies are already installed
Tests fail with tempdir left	Test crash	Clean %TEMP% manually

Branching

• Trunk-based: main is the only long-lived branch and must stay releasable at all times. There is no develop or long-lived release branch — releases are cut by pushing a v* tag, which triggers release.yml to build wheels.
• Branch from the latest main and keep branches short-lived; delete them after merge.
• Name branches after the commit type: feat/<slug>, fix/<slug>, perf/<slug>, docs/<slug> — e.g. feat/paged-cache-settings, fix/moe-routing-consistency.
• Rebase onto main before opening a PR and again whenever conflicts appear. Force-pushes are acceptable on your own feature branches only — never on main.
• PRs are squash-merged: the PR title becomes the commit subject, so write PR titles in the exact commit style (type: subject). The individual branch commits are discarded.
• External contributors work from forks; every PR must pass CI (lint, test (3.12)) and receive at least one review before merge.

Submitting Changes

1. Fork the repo.
2. Create a feature branch: git checkout -b feat/my-feature
3. Make changes following the steps above.
4. Commit with the commit style above.
5. Push: git push origin feat/my-feature
6. Open a Pull Request against main.

Code Review

• All PRs are reviewed. We may request changes.
• CI runs ruff format --check . then ruff check . --select I (no --fix in CI).
• Ensure all tests pass.

License

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

---

Questions? Ask in GitHub Discussions or open an issue.