From 0ff5713ac6c9747ba2b297fabd23b75f62cdd0d7 Mon Sep 17 00:00:00 2001 From: 123kupola <123kupola@gmail.com> Date: Sun, 28 Jun 2026 11:43:43 +0200 Subject: [PATCH] =?UTF-8?q?fix(docs):=20polish=20PR=20workflow=20guide=20+?= =?UTF-8?q?=20README=20=E2=80=94=20correct=20URLs,=20remove=20negative=20f?= =?UTF-8?q?raming?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 22 +++++++++++----------- docs/wiki/pull-requests.md | 37 ++++++++++++++++++++++++++++++++----- 2 files changed, 43 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 35b76bd..69dde99 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ bhyve VMs, Bastille jails) or as a standalone daemon on Linux. | ----------------------- | ----------------------------------------------------------------------- | | `colibri` (root) | Workspace root + probe binaries (colibri-probe, runtime-inventory) | | `colibri-mcp` | MCP bridge for editor integration (Zed, Claude Code) via stdio JSON-RPC | -| `colibri-contracts` | JSON schema contracts (fixture tests) | +| `colibri-contracts` | JSON schema contracts (fixture tests) | | `colibri-deepseek` | DeepSeek cache-hit probe, prefix metering | | `colibri-runtime` | Host status ingestion, runtime inventory | | `colibri-glasspane` | Agent 5-state machine (zot/pi JSONL events → state) | @@ -61,16 +61,16 @@ cargo run --release --bin colibri-runtime-inventory The [wiki](docs/wiki/) records design decisions and architecture docs. Key pages: -| Page | What it covers | -| --------------------------------------------------------- | ------------------------------------------------------- | -| [agent-harness](docs/wiki/agent-harness.md) | Agent lifecycle, zot/pi integration, RPC dispatch | -| [glasspane](docs/wiki/glasspane.md) | 5-state machine, attention system, TUI | -| [hive-routing](docs/wiki/hive-routing.md) | Fleet routing, capability matrix, node registration | -| [cost-dashboard](docs/wiki/cost-dashboard.md) | Per-task cost tracking, proof_text, live dashboard | -| [model-selection-and-eval](docs/wiki/model-selection-and-eval.md) | T2.x eval harness + model selection design | -| [mother-hive](docs/wiki/mother-hive.md) | Mother node coordination (PostgreSQL + MCP over SSH) | -| [pull-requests](docs/wiki/pull-requests.md) | Branch naming, commit format, review workflow | -| [quality-gates](docs/wiki/quality-gates.md) | CI pipeline, fmt/clippy/test/wiki-lint gates | +| Page | What it covers | +| ----------------------------------------------------------------- | ---------------------------------------------------- | +| [agent-harness](docs/wiki/agent-harness.md) | Agent lifecycle, zot/pi integration, RPC dispatch | +| [glasspane](docs/wiki/glasspane.md) | 5-state machine, attention system, TUI | +| [hive-routing](docs/wiki/hive-routing.md) | Fleet routing, capability matrix, node registration | +| [cost-dashboard](docs/wiki/cost-dashboard.md) | Per-task cost tracking, proof_text, live dashboard | +| [model-selection-and-eval](docs/wiki/model-selection-and-eval.md) | T2.x eval harness + model selection design | +| [mother-hive](docs/wiki/mother-hive.md) | Mother node coordination (PostgreSQL + MCP over SSH) | +| [pull-requests](docs/wiki/pull-requests.md) | Branch naming, commit format, review workflow | +| [quality-gates](docs/wiki/quality-gates.md) | CI pipeline, fmt/clippy/test/wiki-lint gates | FreeBSD build: `x86_64-unknown-freebsd` (Rust Tier-2). TLS uses `rustls` for static linking (no `openssl-sys` dependency). diff --git a/docs/wiki/pull-requests.md b/docs/wiki/pull-requests.md index a0bae72..60add67 100644 --- a/docs/wiki/pull-requests.md +++ b/docs/wiki/pull-requests.md @@ -5,6 +5,7 @@ A **pull request (PR)** is how we propose and review changes to the codebase. It ## What is a PR? A PR is a proposal to change code. It shows: + - **What changed** - the diff of modified files - **Why it changed** - commit messages explaining the reasoning - **How it works** - tests proving it works correctly @@ -14,6 +15,7 @@ Every code change goes through a PR before being merged to main. Even small fixe ## Our Workflow ### 1. Create a Branch + ```bash # From main branch git checkout main @@ -28,6 +30,7 @@ git checkout -b descriptive-branch-name ``` ### 2. Make Changes + ```bash # Edit files, run tests cargo fmt @@ -45,6 +48,7 @@ Sam & Claude" ``` ### 3. Push Branch + ```bash git push -u origin descriptive-branch-name ``` @@ -52,11 +56,13 @@ git push -u origin descriptive-branch-name ### 4. Create PR Go to Forgejo web UI or use the link from the push output: + ``` -https://forgejo.smilepowered.org/clawdie/colibri/compare/main...descriptive-branch-name +https://code.smilepowered.org/clawdie/colibri/compare/main...descriptive-branch-name ``` Fill out the PR description: + - **What**: What does this PR do? - **Why**: Why is this change needed? - **How**: How was it implemented? @@ -64,7 +70,8 @@ Fill out the PR description: ### 5. Review -Another agent (or human) reviews the PR: +A reviewer (agent or operator) checks the PR: + - Checks that tests pass - Checks that formatting/clippy are clean - Reviews the code for correctness @@ -73,11 +80,13 @@ Another agent (or human) reviews the PR: ### 6. Merge Once approved: + - Squash merge to main (keeps history clean) - Or regular merge if commits tell a story worth preserving - Delete the branch after merge ### 7. Clean Up + ```bash # Back on main git checkout main @@ -90,6 +99,7 @@ git branch -d descriptive-branch-name ## When to Create a PR **Always create a PR for:** + - Any code changes (even small fixes) - Refactors - New features @@ -101,6 +111,7 @@ git branch -d descriptive-branch-name ## Branch Naming Use descriptive, prefix-style names: + - `fix/` - bug fixes (e.g., `fix/format-drift`) - `feat/` - new features (e.g., `feat/eval-harness`) - `docs/` - documentation (e.g., `docs/model-selection`) @@ -112,6 +123,7 @@ Use descriptive, prefix-style names: Write clear, specific commit messages: **Good:** + ``` fix: resolve format drift in daemon.rs @@ -122,11 +134,13 @@ Sam & Claude ``` **Bad:** + ``` fixed stuff ``` **Structure:** + 1. **Type prefix**: `fix:`, `feat:`, `docs:`, `refactor:`, `test:` 2. **One-line summary**: What changed and why (imperative mood) 3. **Body**: Details if needed (blank line after summary) @@ -147,7 +161,9 @@ Before requesting review (or when reviewing): ## Common Patterns ### Small Fix PR + One commit, one clear fix: + ```bash git commit -m "fix: resolve cargo fmt drift @@ -157,7 +173,9 @@ Sam & Claude" ``` ### Feature PR + Multiple commits telling a story: + ``` feat: add eval harness for task completion @@ -175,7 +193,9 @@ Sam & Claude ``` ### Refactor PR + Rename/reorganize with clear rationale: + ``` refactor: rename golden tests to fixtures @@ -205,11 +225,13 @@ Sam & Claude ## Merging Strategy **Squash merge** when: + - PR has messy commit history - Commits are interdependent - Want clean linear history **Regular merge** when: + - Each commit tells part of a story - Commits are independently reviewable - Want to preserve development history @@ -233,6 +255,7 @@ git push origin --delete my-feature-branch ## Troubleshooting ### PR has merge conflicts + ```bash git checkout my-feature-branch git pull origin main @@ -243,11 +266,13 @@ git push ``` ### Tests fail after push + - Check CI logs - Run tests locally: `cargo test --workspace` - Fix issues, push again ### Reviewer requests changes + - Make requested changes - Commit with clear message: `fix: address review feedback` - Push and re-request review @@ -255,16 +280,18 @@ git push ## Examples from Our Project **Recent PRs in colibri:** + - `feat/eval-harness-phase1` - Added evaluation harness (732 lines changed) -- `refactor/remove-legacy` - Removed legacy references (11 files) -- `rename/golden-to-fixtures` - Renamed test terminology (10 files) -- `fix/smoke-to-test` - Renamed smoke tests to unit tests +- `refactor/rename-golden-to-fixtures` - Renamed golden tests to fixtures (10 files) +- `fix/socket-fmt-drift` - Fixed cargo fmt drift in daemon socket code +- `feat/dynamic-agent-capabilities` - Auto-detected ollama/blender via probe These all followed the pattern: branch → commit → push → PR → review → merge → cleanup. ## Summary PRs are how we collaborate on code. They provide: + - **Visibility**: Everyone sees what's changing - **Review**: Catch bugs before they hit main - **History**: Clear record of why changes were made -- 2.45.3