|
| 1 | +# Maintainers |
| 2 | + |
| 3 | +This document defines how maintainer responsibility, review routing, and |
| 4 | +operational authority work in this project. |
| 5 | + |
| 6 | +codebase-memory-mcp is currently a user-owned repository. Because GitHub teams |
| 7 | +are not available here, all delegated ownership is expressed with individual |
| 8 | +GitHub handles. |
| 9 | + |
| 10 | +## Authority Model |
| 11 | + |
| 12 | +| Role | Scope | Authority in this project | |
| 13 | +| --- | --- | --- | |
| 14 | +| Project owner | Entire repository | Final roadmap, security, release, workflow, and merge authority. | |
| 15 | +| Release operator | Dry-run and release preparation | Prepares release notes, runs checklists, and operates delegated dry runs. Release publication remains owner-gated. | |
| 16 | +| Area reviewer | One technical area | Reviews, tests, reproduces, and recommends merge for that area. Approval is advisory until the project owner approves. | |
| 17 | +| Triage collaborator | Issues and discussions | Labels, deduplicates, reproduces, and requests information. This role has no merge or release authority. | |
| 18 | + |
| 19 | +The binding rule is intentionally simple: all pull requests require |
| 20 | +`@DeusData` approval before merge. `MAINTAINERS.md` routes review; it does not |
| 21 | +override `.github/CODEOWNERS`. |
| 22 | + |
| 23 | +## Project Owner |
| 24 | + |
| 25 | +| Handle | Responsibilities | |
| 26 | +| --- | --- | |
| 27 | +| `@DeusData` | Final authority for merge decisions, releases, security handling, CI policy, repository settings, and maintainer promotion. | |
| 28 | + |
| 29 | +## Area Review Map |
| 30 | + |
| 31 | +Review requests follow this map. Entries marked `TBD` are currently unassigned |
| 32 | +review areas for future co-maintainers. |
| 33 | + |
| 34 | +| Area | Paths | Advisory reviewers | Owner gate | |
| 35 | +| --- | --- | --- | --- | |
| 36 | +| MCP protocol and tool surface | `src/mcp/`, `tests/test_mcp.c` | TBD | `@DeusData` | |
| 37 | +| CLI, install, update, editor integration | `src/cli/`, `src/git/`, `install.sh`, `install.ps1`, `tests/test_cli.c` | TBD | `@DeusData` | |
| 38 | +| Indexing pipeline and graph construction | `src/pipeline/`, `src/discover/`, `src/watcher/`, `tests/test_pipeline.c`, `tests/test_incremental.c` | TBD | `@DeusData` | |
| 39 | +| Language extraction and LSP resolution | `internal/cbm/`, `tools/`, `tests/test_*_lsp.c`, `tests/test_extraction.c`, `tests/test_grammar_*.c` | TBD | `@DeusData` | |
| 40 | +| Store, query, and graph buffers | `src/store/`, `src/cypher/`, `src/graph_buffer/`, `src/simhash/`, `src/semantic/`, `tests/test_store_*.c`, `tests/test_cypher.c` | TBD | `@DeusData` | |
| 41 | +| Foundation/runtime portability | `src/foundation/`, `vendored/`, `tests/test_*` foundation coverage | TBD | `@DeusData` | |
| 42 | +| Graph UI backend and frontend | `src/ui/`, `graph-ui/`, `tests/test_ui.c`, `tests/test_httpd.c` | TBD | `@DeusData` | |
| 43 | +| Tests, repro, smoke, and soak infrastructure | `tests/`, `tests/repro/`, `test-infrastructure/`, `scripts/test.sh`, `scripts/smoke-test.sh`, `scripts/soak-test.sh` | TBD | `@DeusData` | |
| 44 | +| Packaging and distribution | `pkg/`, `install.sh`, `install.ps1`, `server.json`, `glama.json`, `flake.nix`, `flake.lock`, `THIRD_PARTY.md`, `scripts/gen-third-party-notices.sh`, `scripts/gen-ui-licenses.py`, release archive contents | TBD | `@DeusData` | |
| 45 | +| Security and supply chain | `SECURITY.md`, `docs/SECURITY-DISCLOSURE.md`, `scripts/security-*`, `scripts/*license*`, `scripts/*allowlist*`, `.github/workflows/codeql.yml`, `.github/workflows/scorecard.yml` | `@DeusData` only initially | `@DeusData` | |
| 46 | +| CI and release operations | `.github/workflows/`, `scripts/ci/`, `Makefile.cbm` | `@DeusData` only initially | `@DeusData` | |
| 47 | +| Governance and contribution policy | `.github/CODEOWNERS`, `MAINTAINERS.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `DCO`, `LICENSE`, `.github/pull_request_template.md`, issue templates | `@DeusData` only initially | `@DeusData` | |
| 48 | + |
| 49 | +## Operational Authority |
| 50 | + |
| 51 | +Operational authority is stricter than code review authority. |
| 52 | + |
| 53 | +| Operation | Current authority | Project rule | |
| 54 | +| --- | --- | --- | |
| 55 | +| PR validation (`pr.yml`, DCO, CodeQL) | Automatic | Anyone may trigger it by opening or updating a PR. Required checks must pass. | |
| 56 | +| Dry run (`dry-run.yml`) | `@DeusData` | Delegated release operators may run dry runs after promotion. Dry-run delegation does not imply release authority. | |
| 57 | +| Smoke/soak/repro manual runs | `@DeusData` | Area reviewers may operate these runs when delegated for diagnosis. Results are advisory. | |
| 58 | +| Release workflow (`release.yml`) | `@DeusData` only | Owner-only until a release operator is explicitly promoted. Publishing, replacing releases, and tag movement remain owner-gated. | |
| 59 | +| Package registry publishing | `@DeusData` only | Owner-only initially because registry credentials and public packages are irreversible operational surfaces. | |
| 60 | +| Security advisory handling | `@DeusData` only | Do not delegate across advisories. Keep private reports isolated. | |
| 61 | +| Workflow, ruleset, CODEOWNERS, and branch protection changes | `@DeusData` only | Owner-only because these define authority itself. | |
| 62 | + |
| 63 | +## Release Preparation Checklist |
| 64 | + |
| 65 | +Release preparation is a checklist-driven operation. A release is not ready |
| 66 | +until each required gate is green or explicitly waived by the project owner in |
| 67 | +the release notes. |
| 68 | + |
| 69 | +- `dry-run.yml` completes successfully with the release candidate commit. |
| 70 | +- Local performance benchmarks are run on the release operator's machine using |
| 71 | + the release candidate binary and CLI indexing, not test-only shortcuts. |
| 72 | +- `scripts/benchmark-index.sh` records results for the Linux kernel and for at |
| 73 | + least one large open-source project per supported Hybrid LSP family. |
| 74 | +- Benchmark results are compared against the previous release's benchmark logs |
| 75 | + using the same machine class, same repository revisions, same indexing mode, |
| 76 | + and same benchmark script when available. |
| 77 | +- Indexing time must not materially regress compared with the previous release. |
| 78 | + An unexplained slowdown greater than 15% on the same benchmark input is a |
| 79 | + release blocker until investigated or explicitly owner-waived. |
| 80 | +- Node and edge counts must not materially diverge from the previous release |
| 81 | + unless the release intentionally changes extraction behavior. Unexpected |
| 82 | + graph-size shifts require investigation before publishing. |
| 83 | +- Benchmark logs, repository revisions, binary version, machine details, and |
| 84 | + release decision are retained with the release preparation notes. |
| 85 | + |
| 86 | +The current Hybrid LSP release benchmark matrix is: |
| 87 | + |
| 88 | +| LSP family | Required large OSS benchmark | |
| 89 | +| --- | --- | |
| 90 | +| C / C++ | Linux kernel | |
| 91 | +| Go | Kubernetes | |
| 92 | +| Python | CPython or Django | |
| 93 | +| TypeScript / JavaScript / JSX / TSX | TypeScript or VS Code | |
| 94 | +| PHP | Laravel framework | |
| 95 | +| C# | Roslyn | |
| 96 | +| Java | Spring Framework or Elasticsearch | |
| 97 | +| Kotlin | Kotlin compiler or Ktor | |
| 98 | +| Rust | Rust compiler | |
| 99 | + |
| 100 | +The matrix may be updated by PR as the project evolves, but every supported |
| 101 | +Hybrid LSP family keeps at least one large OSS indexing benchmark before a |
| 102 | +release is published. |
| 103 | + |
| 104 | +Repository access follows the same authority model: |
| 105 | + |
| 106 | +- `Triage` is the default collaborator role for issue-only delegation. |
| 107 | +- `Write` access is reserved for collaborators whose operational access has |
| 108 | + been approved by `@DeusData`. |
| 109 | +- Release authority is separate from code review authority. |
| 110 | +- Protected branches, required code-owner review, required status checks, and |
| 111 | + protected release environments are part of the project control model where |
| 112 | + GitHub supports them. |
| 113 | + |
| 114 | +## Promotion Path |
| 115 | + |
| 116 | +Promotion is gradual, explicit, and reversible. |
| 117 | + |
| 118 | +| Stage | Requirements | Capabilities | |
| 119 | +| --- | --- | --- | |
| 120 | +| Trusted contributor | Focused PRs, clean DCO, responsive review cycles. | No elevated access. | |
| 121 | +| Triage collaborator | Consistent issue reproduction and respectful scope control. | Issue triage and review requests. | |
| 122 | +| Area reviewer | Sustained, technically accurate reviews in one area. | Advisory review listing in this file. | |
| 123 | +| Release operator | Proven reliability on dry runs, packaging, and release checklists. | May run delegated dry runs and prepare releases. | |
| 124 | +| Full maintainer | Long-term trust across code, security, release, and governance. | Only after explicit owner decision and updated policy. | |
| 125 | + |
| 126 | +Maintainer promotions are recorded in this file. Binding authority changes are |
| 127 | +recorded in `.github/CODEOWNERS` and repository settings. |
| 128 | + |
| 129 | +## High-Risk Change Rules |
| 130 | + |
| 131 | +These changes always require project-owner review, even if an area reviewer |
| 132 | +approves: |
| 133 | + |
| 134 | +- MCP tool behavior, tool outputs, or protocol capabilities. |
| 135 | +- New process execution, shell invocation, network access, or file access. |
| 136 | +- CI, release, package publishing, installer, or updater changes. |
| 137 | +- Vendored dependency changes, generated grammar changes, or license policy. |
| 138 | +- Security disclosure process, advisories, allowlists, and audit scripts. |
| 139 | +- Repository governance, branch protection, CODEOWNERS, or maintainer roles. |
| 140 | + |
| 141 | +## Review Expectations |
| 142 | + |
| 143 | +- Keep PRs scoped to one issue or one logical change. |
| 144 | +- Reproduce bugs with a failing test before fixing. |
| 145 | +- Treat area-reviewer approval as a technical recommendation, not final merge |
| 146 | + authority. |
| 147 | +- Do not self-approve high-risk changes. |
| 148 | +- Resolve conflicts of interest by asking another reviewer and the owner. |
0 commit comments