diff --git a/CLAUDE.md b/CLAUDE.md index b719b257..18110ebf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,13 +43,13 @@ Detailed: [docs/architecture.md](docs/architecture.md). - **Language policy**: the project targets a global audience — docs and code are English; CJK appears only in test fixtures and locale-suffixed mirrors. Scanned by `make check-cjk`. - **Datetime discipline**: never call `datetime.now()` / `time.time()` directly — use `everos.component.utils.datetime`. Enforced by `make check-datetime`. -Engineering infrastructure overview: [docs/engineering.md](docs/engineering.md). +Contributor engineering reference — build, test, CI gates, branch & commit conventions: [docs/engineering.md](docs/engineering.md). ## Branch strategy `master` = released stable (hidden); `dev` = integration; `feat/* fix/*` → dev; `hotfix/*` → master + dev (sync). -See [docs/engineering.md](docs/engineering.md) for the full GitFlow Lite rationale. +See [.claude/skills/new-branch/SKILL.md](.claude/skills/new-branch/SKILL.md) for the full GitFlow Lite rationale. ## Storage three-piece set @@ -75,7 +75,7 @@ Algorithm assets (prompts, extractors) live in the separate [`everalgo`](https:/ |---|---| | Understand architecture | [docs/architecture.md](docs/architecture.md) | | Understand storage choice | [docs/architecture.md](docs/architecture.md) (storage section) | -| Engineering tooling overview | [docs/engineering.md](docs/engineering.md) | +| Build, test, CI & conventions | [docs/engineering.md](docs/engineering.md) | | Add a new module | [.claude/rules/init-py-and-reexport.md](.claude/rules/init-py-and-reexport.md) | | Make a commit | use `/commit` | | Open a branch / PR | use `/new-branch` / `/pr` | diff --git a/README.md b/README.md index c63c4008..7f221d8b 100644 --- a/README.md +++ b/README.md @@ -644,7 +644,7 @@ Explore stored entities and relationships in a graph interface. Frontend demo; b - [docs/everos-demo.md](docs/everos-demo.md) — Demo scope and TUI source layout - [docs/how-memory-works.md](docs/how-memory-works.md) — Markdown, SQLite, LanceDB, and recall flow - [docs/use-cases.md](docs/use-cases.md) — Full use-case gallery and integration examples -- [docs/engineering.md](docs/engineering.md) — Engineering and CI tooling +- [docs/engineering.md](docs/engineering.md) — Contributor engineering reference: build, test, CI, conventions - [docs/migration-to-1.0.0.md](docs/migration-to-1.0.0.md) — Legacy API migration notes - [CHANGELOG.md](CHANGELOG.md) — Release notes - [CONTRIBUTING.md](CONTRIBUTING.md) — How to contribute diff --git a/README.zh-CN.md b/README.zh-CN.md index 2d7feb15..b7a899e9 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -653,7 +653,7 @@ Claude Code 的持久记忆插件。自动保存并回忆过去 coding sessions - [docs/everos-demo.md](docs/everos-demo.md) - Demo 范围与 TUI 源码布局 - [docs/how-memory-works.md](docs/how-memory-works.md) - Markdown、SQLite、LanceDB 与 recall flow - [docs/use-cases.md](docs/use-cases.md) - 完整使用场景 gallery 和集成示例 -- [docs/engineering.md](docs/engineering.md) - 工程与 CI tooling +- [docs/engineering.md](docs/engineering.md) - 贡献者工程参考:构建、测试、CI 与规范 - [docs/migration-to-1.0.0.md](docs/migration-to-1.0.0.md) - Legacy API 迁移说明 - [CHANGELOG.md](CHANGELOG.md) - 发布记录 - [CONTRIBUTING.md](CONTRIBUTING.md) - 如何贡献 diff --git a/docs/architecture.md b/docs/architecture.md index afb5efe3..72d3bb51 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -282,5 +282,5 @@ prevent external types from leaking into upper layers: ## Further reading - [docs/overview.md](overview.md) — vision and scope -- [docs/engineering.md](engineering.md) — engineering tooling and CI / CD +- [docs/engineering.md](engineering.md) — contributor engineering reference: build, test, CI, conventions - [.claude/rules/architecture.md](../.claude/rules/architecture.md) — short-form rules for Claude Code diff --git a/docs/engineering.md b/docs/engineering.md index 2a97cbb5..670aaa20 100644 --- a/docs/engineering.md +++ b/docs/engineering.md @@ -1,574 +1,113 @@ -# Engineering & Dev-Efficiency Infrastructure +# Engineering Reference -> Companions: business architecture lives in [architecture.md](architecture.md); -> hard coding constraints live in [../.claude/rules/](../.claude/rules/). -> This document covers the surrounding tooling, configuration, and processes -> — what we adopted, what role each piece plays, and how they fit together. +> Companion docs: system design lives in [architecture.md](architecture.md); +> coding rules live in [../.claude/rules/](../.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 -## 1. Scope - -Engineering / dev-efficiency infrastructure does not solve business problems — -it solves **team + code + time** problems: - -``` -┌──────────────────────────────────────────────────────────┐ -│ │ -│ Business architecture (docs/architecture.md) │ -│ — answers "how to build the system" │ -│ │ -│ Engineering rules (.claude/rules/) │ -│ — answers "how to write the code" │ -│ │ -│ Engineering / dev-efficiency infrastructure (this doc) │ -│ — answers "how the team collaborates, │ -│ how code is auto-checked, │ -│ how releases are automated, │ -│ how tools land in the project" │ -│ │ -└──────────────────────────────────────────────────────────┘ -``` - -Reasons this is documented separately: - -- **Cross-project reusable** — `CLAUDE.md` / rules / `pyproject.toml` are - patterns, not content. The next project can adopt them as-is. -- **Decoupled from business** — business architecture changes do not affect - these; upgrading these does not affect business. -- **Onboarding-oriented** — new contributors read this first to understand - what the tooling looks like. - ---- - -## 2. Infrastructure overview - -``` -┌─────────────────────────────────────────────────────────────────────┐ -│ Team collaboration / Code quality / CI/CD │ -├─────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌─ Claude Code engineering layer ────────────────────────────┐ │ -│ │ │ │ -│ │ CLAUDE.md ← team-shared context (auto loaded into │ │ -│ │ system prompt) │ │ -│ │ .claude/ │ │ -│ │ ├── CLAUDE.md subdir context (optional) │ │ -│ │ ├── rules/ (10) path-scoped hard coding rules │ │ -│ │ ├── skills/ (5) slash command workflows │ │ -│ │ └── settings.json permissions allowlist │ │ -│ │ │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌─ Code quality gates ───────────────────────────────────────┐ │ -│ │ │ │ -│ │ pre-commit runs locally before commit │ │ -│ │ ├ ruff (lint+fmt) │ │ -│ │ ├ trailing-whitespace / end-of-file-fixer │ │ -│ │ ├ check-yaml / check-toml │ │ -│ │ ├ check-added-large-files (≥1MB warn) │ │ -│ │ ├ detect-private-key │ │ -│ │ └ gitlint (commit-msg stage) │ │ -│ │ │ │ -│ │ ruff lint + format │ │ -│ │ (replaces black / isort / flake8) │ │ -│ │ import-linter DDD layer-direction enforcement │ │ -│ │ pytest unit / integration │ │ -│ │ │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌─ Dependencies & build ─────────────────────────────────────┐ │ -│ │ │ │ -│ │ uv sole package manager │ │ -│ │ (no `pip install`) │ │ -│ │ pyproject.toml src layout + extras + groups │ │ -│ │ uv.lock checked in; CI uses --frozen │ │ -│ │ hatchling wheel build backend │ │ -│ │ Makefile unified entry; CI calls it │ │ -│ │ config/default.toml default settings (shipped) │ │ -│ │ │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌─ Dual-platform CI/CD ──────────────────────────────────────┐ │ -│ │ │ │ -│ │ Primary: GitLab CI .gitlab-ci.yml │ │ -│ │ Mirror: GitHub Actions .github/workflows/ci.yml │ │ -│ │ Both invoke Makefile targets; the Makefile is the │ │ -│ │ single source of truth for commands. │ │ -│ │ │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌─ Collaboration workflow ───────────────────────────────────┐ │ -│ │ │ │ -│ │ Branch model: dev / master (GitFlow Lite) │ │ -│ │ PR / MR templates: same template across platforms │ │ -│ │ CODEOWNERS: by DDD layer ownership │ │ -│ │ ISSUE_TEMPLATE: bug / feature / config │ │ -│ │ CONTRIBUTING.md: contributor onboarding │ │ -│ │ │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 3. Claude Code engineering layer - -### 3.1 Loading mechanism - -Claude Code automatically loads the following into the system prompt at -session start (no manual import): - -``` -┌────────────────────────┬──────────────────────────────────────────┐ -│ File │ Purpose │ -├────────────────────────┼──────────────────────────────────────────┤ -│ CLAUDE.md (repo root) │ Team-shared context: architecture │ -│ │ overview, commands, convention index │ -│ .claude/rules/*.md │ Hard coding constraints │ -│ │ (path-scoped on-demand load) │ -│ .claude/settings.json │ Permissions allowlist (not in prompt) │ -│ ~/.claude/CLAUDE.md │ User-level (personal preferences) │ -│ CLAUDE.local.md │ Project-local personal (gitignored) │ -└────────────────────────┴──────────────────────────────────────────┘ -``` - -### 3.2 Rules (10 files, path-scoped) - -| File | Paths (auto-load condition) | +| Tool | Role | |---|---| -| architecture.md | always loaded (no paths) | -| code-style.md | always loaded (no paths) | -| language-policy.md | always loaded (no paths) | -| imports.md | `src/**/*.py`, `tests/**/*.py` | -| init-py-and-reexport.md | `src/**/__init__.py`, `src/**/*.py` | -| module-docstring.md | `src/{infra,memory,service,component,core}/**/*.py` | -| async-programming.md | `src/**/*.py`, `tests/**/*.py` | -| datetime-handling.md | `src/**/*.py`, `tests/**/*.py` | -| logging-observability.md | `src/**/*.py` | -| testing.md | `tests/**/*.py` | - -**Why path-scoped**: avoid loading 1000+ lines of rules every session -(~5–8K tokens). At startup only architecture + code-style + language-policy -load (~1.5–2K tokens); the rest load on demand when Claude Code reads a -matching `.py` file. - -### 3.3 Skills (5 slash commands) - -| Command | Purpose | When to use | -|---|---|---| -| `/commit` | Generate Gitmoji-format commit message | After a focused change, ready to commit | -| `/new-branch` | Create branch under dev/master strategy | Starting a new feat / fix / hotfix | -| `/pr` | Create GitLab MR or GitHub PR with template | Ready to merge | -| `/add-memory-kind` | Scaffold a new business memory kind end-to-end | Adding a new memory type (md + sqlite + lancedb) | -| `/release` | Cut a PyPI release (rc / stable) | Shipping a version | - -Skills and rules use **independent loading mechanisms**: rules auto-load -into the system prompt, skills only trigger when the user types `/`. - -### 3.4 settings.json - -```json -{ - "permissions": { - "allow": ["Bash(uv sync*)", "Bash(make*)", "Bash(uv run pytest*)", ...] - } -} -``` - -**Purpose**: reduce permission prompts. Team-shared config goes into -`settings.json` (in git); personal preferences go into `settings.local.json` -(gitignored). - ---- - -## 4. Code quality gates - -``` - ┌──────────────────────────────────────────────────────┐ - │ Each stage can independently fail the change │ - └──────────────────────────────────────────────────────┘ - -[Local editor] - │ - ▼ -Stage 1: editor real-time feedback - ├ ruff (lint + format) on save - └ path-relevant .claude/rules guide Claude Code - - │ - ▼ -Stage 2: pre-commit (triggered by `git commit`) - ├ ruff fix + format - ├ trailing-whitespace, end-of-file-fixer - ├ check-yaml, check-toml - ├ check-added-large-files (≥1MB) - ├ check-merge-conflict - ├ detect-private-key - └ gitlint (commit-msg stage; rejects malformed messages) - - │ - ▼ -Stage 3: local `make ci` (manual, before push) - ├ make lint (ruff + format-check + import-linter + datetime + openapi-drift) - ├ make test (pytest tests/unit) - └ make integration (pytest tests/integration) - - │ - ▼ -Stage 4: CI (PR triggered, GitLab + GitHub) - └ re-runs the same `make lint / test / integration` targets - - │ - ▼ -Stage 5: PR / MR review - ├ ≥ 1 approval - └ all threads resolved + all CI green -``` - -**Key design**: when any stage fails, **never merge** — there is no -`--no-verify` / `--allow-failure` escape hatch. - ---- - -## 5. Dependencies & build - -### 5.1 pyproject.toml overview - -```toml -[project] -name = "everos" -requires-python = ">=3.12" -dependencies = [...] # runtime deps (minimal set) - -[project.optional-dependencies] -multimodal = [...] # extras (install on demand) - -[build-system] -requires = ["hatchling"] -build-backend = "hatchling.build" - -[tool.hatch.build.targets.wheel] -packages = ["src/everos"] # src layout - -[project.scripts] -everos = "everos.entrypoints.cli.main:app" # exposes CLI command - -[tool.ruff] # code style -[tool.pytest.ini_options] # tests -[tool.coverage.run] # coverage (unit+integration; make cov gates at 80%) -[tool.importlinter] # dependency direction - -[dependency-groups] -dev = ["ruff", "pytest", "pytest-asyncio", "pytest-cov", - "pytest-rerunfailures", "import-linter", "pre-commit", - "pyinstrument", "ipdb"] -``` - -**Single-file principle**: configuration that used to live in `pylintrc`, -`pytest.ini`, `.isort.cfg` is **all consolidated into `pyproject.toml`**. - -### 5.2 Makefile commands - -``` -make help list all targets -make install uv sync --frozen -make format ruff fix + format -make lint ruff + format --check + import-linter + datetime + openapi-drift -make test pytest tests/unit -make integration pytest tests/integration -make cov pytest unit+integration with coverage, gate at 80% -make ci lint + test + integration ← CI invokes these targets -make clean clear caches -``` +| [uv](https://docs.astral.sh/uv/) | sole package manager (`uv sync`; do not use `pip install`) | +| [hatchling](https://hatch.pypa.io/) | wheel build backend (src layout under `src/everos`) | +| [ruff](https://docs.astral.sh/ruff/) | lint + format (replaces black / isort / flake8) | +| [import-linter](https://import-linter.readthedocs.io/) | enforces the DDD layer dependency direction | +| [pytest](https://docs.pytest.org/) | unit + integration tests | +| [pre-commit](https://pre-commit.com/) | local gate run before each commit | +| `Makefile` | single entry point for every command — CI invokes the same targets | -> Plus `install-deps` (CI's `uv sync --frozen`), `openapi` (regenerate -> `docs/openapi.json`), `check-openapi` / `check-datetime` (the lint -> sub-gates), and `check-cjk` (advisory) — see the `Makefile` for the -> full list. +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. -**Single source of truth**: CI configuration only invokes `make `, -preventing drift between GitHub and GitLab. Local and CI run identical -commands. - -### 5.3 Configuration model - -Settings are loaded in ascending priority: - -1. `config/default.toml` (shipped with the package; lowest priority) -2. `/everos.toml` (user config; optional) -3. `EVEROS_*` environment variables (highest priority) - -`everos init [--root PATH]` generates starter config files -(`everos.toml` + `ome.toml`) in the memory root. `everos.toml` holds -all config (API keys, model, storage); override individual fields with -`EVEROS_*` env vars. Inspect the effective config with -`everos config show [--root PATH]`. - -Key `EVEROS_*` env vars: - -``` -EVEROS_LLM__MODEL # model name (provider-agnostic) -EVEROS_LLM__API_KEY # any OpenAI-protocol API key -EVEROS_LLM__BASE_URL # optional: custom endpoint (Ollama bridge etc.) -EVEROS_ROOT # memory-root (default ~/.everos) -EVEROS_LOG_LEVEL -TZ -``` - ---- - -## 6. Dual-platform CI/CD - -### 6.1 Dual-platform strategy - -``` -┌──────────────────────────────────────────────────────────┐ -│ │ -│ Primary: GitLab CI (.gitlab-ci.yml) │ -│ ├ internal team dev stages: lint / test │ -│ ├ MR triggered │ -│ └ uv cache (keyed by uv.lock) │ -│ │ -│ Mirror: GitHub Actions (.github/workflows/ci.yml) │ -│ ├ public OSS mirror same make targets │ -│ ├ push + PR triggered │ -│ └ astral-sh/setup-uv@v3 │ -│ │ -│ Consistency: │ -│ ├ Makefile is the single source of CI commands │ -│ └ pre-commit runs locally first to reduce CI churn │ -│ │ -└──────────────────────────────────────────────────────────┘ -``` - -### 6.2 CI checklist - -| Check | Tool | Platform | Failure condition | -|---|---|---|---| -| Lint | `make lint` (ruff + format-check + import-linter + datetime + openapi-drift) | both | any error | -| Layer direction | `make lint` (lint-imports inside) | both | layer violation | -| Unit | `make test` (pytest tests/unit) | both | any failure | -| Integration | `make integration` (pytest tests/integration) | both | any failure (PR + master/dev push only) | - -Commit message format is enforced **locally** via `gitlint` in the -`commit-msg` pre-commit stage; it does not run in CI. - -### 6.3 Branch protection - -| Branch | GitLab rule | GitHub rule | -|---|---|---| -| **master** | no direct push; MR + 1 approval + green pipeline | branch protection + 1 review + status checks | -| **dev** | same as above | same as above | -| feat / fix / hotfix | free push; rebase parent before merge | same | - ---- - -## 7. Collaboration workflow - -### 7.1 Branch model (GitFlow Lite) - -``` - v0.1 v0.2 v1.0 - ▲ ▲ ▲ - │ release PR │ release PR │ release PR - │ (dev→master+tag) │ (dev→master+tag) │ (dev→master+tag) -master ●──────────────────────●─────────────●──────────────────●──────────────────────────────────●────► stable / released - │ ▲ │ │ - │ │ merge hotfix │ │ - │ │ │ │ - │ ●──●──┘ │ │ - │ │ hotfix branch │ │ - │ │ (cut from master) │ │ - │ │ │ │ - │ ▼ sync to dev │ │ - │ │ │ │ -dev ●──●──●──●──●──●──●──●──●─●──●──●─●──●──●──●──●──●──●──●──●─●──●──●──●──●──●──●──●──●──●──●──●─────► integration - ▲ ↑ ↑ ↑ - │ release point release point release point - feat/A (dev HEAD → (dev HEAD → (dev HEAD → - ●──●──● master + v0.1) master + v0.2) master + v1.0) - - - feat/* : cut from dev → PR → merge into dev - hotfix/* : cut from master → merge into master + sync into dev (double merge) - release : dev → master + tag on master (no separate release branch) - - Vertical │ in the diagram = "dev HEAD merged into master via release PR + v0.x tag" -``` - -Details in [../.claude/skills/new-branch/SKILL.md](../.claude/skills/new-branch/SKILL.md). - -### 7.2 PR / MR template (shared across platforms) - -Six sections: changes / target branch / scope / API impact / tests / -checklist. - -File locations: - -- GitLab: `.gitlab/merge_request_templates/default.md` -- GitHub: `.github/PULL_REQUEST_TEMPLATE.md` - -### 7.3 Code ownership - -The `.gitlab/CODEOWNERS` file was removed (commit `e870927`) to avoid -leaking internal accounts. Code ownership is now managed via GitLab -project-level settings (Merge Request approval rules). - -### 7.4 Commit convention (Gitmoji) +## Local development +```bash +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 ``` -✨ feat: new feature -🐛 fix: bug fix -♻️ refactor: refactoring (no behavior change) -✅ test: add / update tests -📝 docs: documentation -🎨 style: formatting -⚡️ perf: performance optimization -🔧 chore: configuration / build -🚧 wip: work in progress (must not land on master) -``` - -`gitlint` enforces format **locally** (commit-msg pre-commit stage). See -[../.claude/skills/commit/SKILL.md](../.claude/skills/commit/SKILL.md). ---- - -## 8. Issue templates / user support - -``` -.github/ISSUE_TEMPLATE/ -├── bug_report.md software deps: lancedb / sqlite / ruff -├── feature_request.md generic template -└── config.yml disable blank issue + Discord / Discussions links +CI runs the **same** `make` targets, so a green `make ci` locally predicts a +green pipeline. -CONTRIBUTING.md contributor onboarding: setup / code style / - branch / commit / PR / testing -``` +### Configuration ---- +Settings load in ascending priority: -## 9. Infrastructure summary table +1. `src/everos/config/default.toml` — shipped with the package (lowest) +2. `/everos.toml` — user config (optional) +3. `EVEROS_*` environment variables (highest) -``` -┌─────────────────────┬──────────────────────────────────────┬─────────────┐ -│ Facility │ Location / file │ Failure │ -│ │ │ impact │ -├─────────────────────┼──────────────────────────────────────┼─────────────┤ -│ CLAUDE.md │ /CLAUDE.md │ cc loses │ -│ │ │ context │ -│ Team rules │ /.claude/rules/ (10) │ cc unaware │ -│ │ │ of conv. │ -│ Team skills │ /.claude/skills/ (5) │ no slash │ -│ │ │ workflows │ -│ Permissions │ /.claude/settings.json │ cc prompts │ -│ │ │ on each op │ -├─────────────────────┼──────────────────────────────────────┼─────────────┤ -│ pyproject │ /pyproject.toml │ build fail │ -│ Lock file │ /uv.lock │ dep drift │ -│ Makefile │ /Makefile │ no unified │ -│ │ │ entry │ -│ pre-commit │ /.pre-commit-config.yaml │ no local │ -│ │ │ gate │ -│ default config │ /src/everos/config/default.toml │ newcomers │ -│ │ │ lost on cfg│ -├─────────────────────┼──────────────────────────────────────┼─────────────┤ -│ GitLab CI │ /.gitlab-ci.yml │ MR cannot │ -│ │ │ merge │ -│ GitHub Actions │ /.github/workflows/ci.yml │ PR cannot │ -│ │ │ merge │ -│ Code ownership │ GitLab project settings │ no auto │ -│ │ (approval rules) │ reviewer │ -│ GitLab MR template │ /.gitlab/merge_request_templates/ │ no MR temp │ -│ GitHub PR template │ /.github/PULL_REQUEST_TEMPLATE.md │ no PR temp │ -│ Issue templates │ /.github/ISSUE_TEMPLATE/ (3) │ scattered │ -│ CONTRIBUTING │ /CONTRIBUTING.md │ contrib. │ -│ │ │ confused │ -└─────────────────────┴──────────────────────────────────────┴─────────────┘ -``` +Run `everos init` to generate starter config and `everos config show` to +inspect the effective result. Full reference: [configuration.md](configuration.md). ---- +## Quality gates -## 10. Future extensions +Each stage can independently fail a change; there is no `--no-verify` bypass. ``` -Near-term - ☑ Coverage threshold — `make cov` now gates at 80% (unit + integration) - □ /new-module skill: scaffold a subpackage that complies with rules - □ /run-eval skill: run behavior-consistency eval - □ ruff rule sets: add D (docstring), ANN (annotations) - -Mid-term (v1.2 – v1.3) - □ Type checking re-introduction (pyright or mypy) once hot paths stabilize - □ release-please / Conventional Commits → automated changelog - □ pre-commit autoupdate cadence - □ Performance benchmark CI with historical comparison - -Long-term (v2+) - □ /security-review skill: automated security review - □ Mutation testing (mutmut) - □ Multi-Python version matrix (3.12 / 3.13) - □ Automated PyPI wheel upload +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 ``` ---- - -## 11. On investing in engineering infrastructure - -``` -┌──────────────────────────────────────────────────────────┐ -│ │ -│ Plain business code ≠ an engineering project │ -│ │ -│ Engineering project = business code + │ -│ coding rules + │ -│ quality gates (pre-commit + CI) + │ -│ automation (Makefile + skills) + │ -│ collaboration (branch + PR + │ -│ CODEOWNERS) + │ -│ knowledge base (CLAUDE.md + │ -│ rules + docs) │ -│ │ -│ The earlier this infrastructure lands, the faster and │ -│ farther the team can run. │ -│ │ -└──────────────────────────────────────────────────────────┘ -``` +## Continuous integration -Old project vs. new project after this rewrite: +CI runs on GitHub Actions ([.github/workflows/](../.github/workflows/)). Every +pull request into `main` must pass: -| Dimension | Old project | New project | +| Check | Command | Guards | |---|---|---| -| Lint tools | black + isort + pylint | ruff (single tool) | -| Config files | pyproject + pylintrc + pyrightconfig + pytest.ini | unified pyproject.toml | -| pre-commit | basic | adds gitlint commit-msg + import / yaml / private-key checks | -| Layer direction | not enforced | import-linter enforced in CI | -| Commit format | freeform | gitlint pre-commit hook (Gitmoji) | -| Claude Code integration | partial rules | rules + skills + settings (full) | -| CI platform | GitLab only | GitLab + GitHub mirror, both calling Makefile | -| Tests | basic | unit + integration + golden + coverage report | - -These are not perfectionism — they are baseline requirements for -**multi-person collaboration, long-term maintenance, and sustainable -evolution**. - ---- +| 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](https://www.conventionalcommits.org/): `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](../.github/PULL_REQUEST_TEMPLATE.md) + (changes / scope / API impact / tests / checklist). +- **Issues** use the templates under [.github/ISSUE_TEMPLATE/](../.github/ISSUE_TEMPLATE/). + +See [CONTRIBUTING.md](../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 -## 12. References - -- Hard coding rules: [../.claude/rules/](../.claude/rules/) (auto-loaded by Claude Code) -- Slash command workflows: [../.claude/skills/](../.claude/skills/) -- Contributor onboarding: [../CONTRIBUTING.md](../CONTRIBUTING.md) - Architecture: [architecture.md](architecture.md) -- Claude Code memory mechanism: [code.claude.com/docs/en/memory.md](https://code.claude.com/docs/en/memory.md) -- Claude Code skills: [code.claude.com/docs/en/skills.md](https://code.claude.com/docs/en/skills.md) -- ruff: [docs.astral.sh/ruff](https://docs.astral.sh/ruff/) -- import-linter: [import-linter.readthedocs.io](https://import-linter.readthedocs.io/) -- gitlint: [jorisroovers.com/gitlint](https://jorisroovers.com/gitlint/) -- uv: [docs.astral.sh/uv](https://docs.astral.sh/uv/) -- pre-commit: [pre-commit.com](https://pre-commit.com/) -- Gitmoji: [gitmoji.dev](https://gitmoji.dev/) -- GitLab CI: [docs.gitlab.com/ee/ci](https://docs.gitlab.com/ee/ci/) -- GitHub Actions: [docs.github.com/en/actions](https://docs.github.com/en/actions) -- CODEOWNERS: [docs.gitlab.com/ee/user/project/codeowners](https://docs.gitlab.com/ee/user/project/codeowners/) +- Coding rules: [../.claude/rules/](../.claude/rules/) +- Contributor onboarding: [../CONTRIBUTING.md](../CONTRIBUTING.md) +- [uv](https://docs.astral.sh/uv/) · + [ruff](https://docs.astral.sh/ruff/) · + [import-linter](https://import-linter.readthedocs.io/) · + [pre-commit](https://pre-commit.com/) · + [Conventional Commits](https://www.conventionalcommits.org/) diff --git a/docs/index.md b/docs/index.md index 6d331572..3b593527 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,6 +4,16 @@ Documentation for [EverOS](../README.md) — md-first memory extraction framework. Organised by [Diátaxis](https://diataxis.fr/) — what kind of question you have determines which section to read. +## Tutorials + +Learning-oriented entry points — start here to get a feel for the system +before wiring it into a real workflow. + +| Doc | Purpose | +|---|---| +| [everos-demo.md](everos-demo.md) | `everos demo` — local educational TUI to feel the memory lifecycle before configuring keys | +| [use-cases.md](use-cases.md) | Worked examples and integrations showing what persistent memory enables, to study and adapt | + ## Reference Technical reference: contracts, commands, schemas — read these when you @@ -42,14 +52,14 @@ specific thing (drain a queue, recover from a stuck row, etc.). | [cascade_runbook.md](cascade_runbook.md) | Cascade subsystem ops — drain queue, recover stuck rows | | [locomo_benchmark.md](locomo_benchmark.md) | LoCoMo benchmark — run and evaluate | -## Engineering / Internal +## Engineering -For maintainers and contributors working on the framework itself, -not for using it. +For contributors working on the framework itself — how to build, test, +and ship a change. | Doc | Purpose | |---|---| -| [engineering.md](engineering.md) | Engineering & dev-efficiency infrastructure (CI / tooling / Claude Code) | +| [engineering.md](engineering.md) | Contributor engineering reference — build, test, CI gates, branch & commit conventions | ## See also @@ -59,6 +69,8 @@ Top-level project files live next to the repo root: - [QUICKSTART.md](../QUICKSTART.md) — 5-minute walkthrough (install → service → search) - [CONTRIBUTING.md](../CONTRIBUTING.md) — how to contribute (issue-only model) - [CHANGELOG.md](../CHANGELOG.md) — release notes +- [release-notes-1.1.0.md](release-notes-1.1.0.md) — EverOS 1.1.0 highlights (Knowledge, Reflection, OME) +- [migration-to-1.0.0.md](migration-to-1.0.0.md) — migrate off pre-1.0.0 APIs / infrastructure - [SECURITY.md](../SECURITY.md) — security policy & private vulnerability reporting - [CITATION.md](../CITATION.md) — academic citation info - [ACKNOWLEDGMENTS.md](../ACKNOWLEDGMENTS.md) — third-party acknowledgments