Skip to content

engineering.md

Latest commit

 

History

History
113 lines (89 loc) · 4.96 KB

engineering.md

File metadata and controls

113 lines (89 loc) · 4.96 KB

Engineering Reference

Companion docs: system design lives in architecture.md; coding rules live in ../.claude/rules/. This document is the contributor-facing reference for building, testing, and shipping a change — the toolchain, the CI gates, and the branch / commit conventions your pull request must satisfy.

Toolchain

Tool Role
uv sole package manager (uv sync; do not use pip install)
hatchling wheel build backend (src layout under src/everos)
ruff lint + format (replaces black / isort / flake8)
import-linter enforces the DDD layer dependency direction
pytest unit + integration tests
pre-commit local gate run before each commit
Makefile single entry point for every command — CI invokes the same targets

All tool configuration lives in a single pyproject.toml (ruff, pytest, coverage, and the import-linter layer contracts) — there are no separate pylintrc / pytest.ini / .isort.cfg files.

Local development

make install      # uv sync --frozen
make format       # ruff fix + format
make lint         # ruff check + format-check + import-linter + datetime/asset/name guards
make test         # pytest tests/unit
make integration  # pytest tests/integration
make cov          # unit + integration with coverage (gate: 80%)
make ci           # lint + test + integration  — run this before pushing
make help         # list every target

CI runs the same make targets, so a green make ci locally predicts a green pipeline.

Configuration

Settings load in ascending priority:

  1. src/everos/config/default.toml — shipped with the package (lowest)
  2. <memory-root>/everos.toml — user config (optional)
  3. EVEROS_* environment variables (highest)

Run everos init to generate starter config and everos config show to inspect the effective result. Full reference: configuration.md.

Quality gates

Each stage can independently fail a change; there is no --no-verify bypass.

1. Editor      ruff (lint + format) on save
2. pre-commit  ruff, trailing-whitespace / EOF, yaml & toml checks,
               large-file & private-key guards, merge-conflict check,
               and gitlint (commit-msg stage) — see "Commits" below
3. make ci     lint + unit + integration — run before pushing
4. GitHub CI   re-runs the same make targets on every pull request
5. Review      1 approval + all conversations resolved + all checks green

Continuous integration

CI runs on GitHub Actions (.github/workflows/). Every pull request into main must pass:

Check Command Guards
lint make lint ruff style, DDD layer direction (import-linter), datetime discipline, asset & deprecated-name guards
unit tests make test tests/unit
integration tests make integration tests/integration
package build make package the wheel builds and imports cleanly
docs make docs-check Markdown and internal-link validity
commit messages / PR title make check-commits / make check-pr-title Conventional Commits format

main is a protected branch: no direct pushes; changes land through a reviewed pull request with all checks green.

Contributing workflow

  • Branch off main, then open a pull request back into main.
  • Commits and the PR title follow Conventional Commits: type(scope): subject, with the subject ≤ 72 characters and no leading emoji. Allowed types: feat, fix, refactor, test, docs, style, perf, chore, build, ci, revert. This is enforced both locally (gitlint, commit-msg stage) and in CI.
  • Pull requests use .github/PULL_REQUEST_TEMPLATE.md (changes / scope / API impact / tests / checklist).
  • Issues use the templates under .github/ISSUE_TEMPLATE/.

See CONTRIBUTING.md for the full onboarding walkthrough.

This repository also ships Claude Code configuration — coding rules under .claude/rules/ and slash-command workflows under .claude/skills/ — that encode the conventions above. It is optional convenience tooling: using Claude Code is not required to contribute, and the CI gates remain the source of truth.

References