55f0bbe97e
Closes #1252 - Assignment-as-lock protocol for humans and agents - Branch naming conventions - PR requirements (rebase, reference issues, no bytecode) - Path conventions table - Feature manifest workflow - Stale PR policy documentation
156 lines
4.6 KiB
Markdown
156 lines
4.6 KiB
Markdown
# Contributing to The Nexus
|
|
|
|
## Issue Assignment — The Lock Protocol
|
|
|
|
**Rule: Assign before you code.**
|
|
|
|
Before starting work on any issue, you **must** assign it to yourself. If an issue is already assigned to someone else, **do not submit a competing PR**.
|
|
|
|
### For Humans
|
|
|
|
1. Check the issue is unassigned
|
|
2. Assign yourself via the Gitea UI (right sidebar → Assignees)
|
|
3. Start coding
|
|
|
|
### For Agents (Claude, Perplexity, Mimo, etc.)
|
|
|
|
1. Before generating code, call the Gitea API to check assignment:
|
|
```
|
|
GET /api/v1/repos/{owner}/{repo}/issues/{number}
|
|
→ Check assignees array
|
|
```
|
|
2. If unassigned, self-assign:
|
|
```
|
|
POST /api/v1/repos/{owner}/{repo}/issues/{number}/assignees
|
|
{"assignees": ["your-username"]}
|
|
```
|
|
3. If already assigned, **stop**. Post a comment offering to help instead.
|
|
|
|
### Why This Matters
|
|
|
|
On April 11, 2026, we found 12 stale PRs caused by Rockachopa and the `[claude]` auto-bot racing on the same issues. The auto-bot merged first, orphaning the manual PRs. Assignment-as-lock prevents this race condition.
|
|
|
|
---
|
|
|
|
## Branch Protection & Review Policy
|
|
|
|
All repositories enforce these rules on `main`:
|
|
|
|
| Rule | Status |
|
|
|------|--------|
|
|
| Require Pull Request for merge | ✅ Enabled |
|
|
| Require 1 approval before merge | ✅ Enabled |
|
|
| Dismiss stale approvals on new commits | ✅ Enabled |
|
|
| Require CI to pass (where CI exists) | ⚠️ Conditional |
|
|
| Block force pushes to `main` | ✅ Enabled |
|
|
| Block deletion of `main` branch | ✅ Enabled |
|
|
|
|
### Default Reviewer Assignments
|
|
|
|
| Repository | Required Reviewers |
|
|
|------------|-------------------|
|
|
| `hermes-agent` | `@perplexity`, `@Timmy` |
|
|
| `the-nexus` | `@perplexity` |
|
|
| `timmy-home` | `@perplexity` |
|
|
| `timmy-config` | `@perplexity` |
|
|
|
|
### CI Enforcement Status
|
|
|
|
| Repository | CI Status |
|
|
|------------|-----------|
|
|
| `hermes-agent` | ✅ Active |
|
|
| `the-nexus` | ⚠️ CI runner pending (#915) |
|
|
| `timmy-home` | ❌ No CI |
|
|
| `timmy-config` | ❌ Limited CI |
|
|
|
|
---
|
|
|
|
## Branch Naming
|
|
|
|
Use descriptive prefixes:
|
|
|
|
| Prefix | Use |
|
|
|--------|-----|
|
|
| `feat/` | New features |
|
|
| `fix/` | Bug fixes |
|
|
| `epic/` | Multi-issue epic branches |
|
|
| `docs/` | Documentation only |
|
|
|
|
Example: `feat/mnemosyne-memory-decay`
|
|
|
|
---
|
|
|
|
## PR Requirements
|
|
|
|
1. **Rebase before merge** — PRs must be up-to-date with `main`. If you have merge conflicts, rebase locally and force-push.
|
|
2. **Reference the issue** — Use `Closes #NNN` in the PR body so Gitea auto-closes the issue on merge.
|
|
3. **No bytecode** — Never commit `__pycache__/` or `.pyc` files. The `.gitignore` handles this, but double-check.
|
|
4. **One feature per PR** — Avoid omnibus PRs that bundle multiple unrelated features. They're harder to review and more likely to conflict.
|
|
|
|
---
|
|
|
|
## Path Conventions
|
|
|
|
| Module | Canon Path |
|
|
|--------|-----------|
|
|
| Mnemosyne (backend) | `nexus/mnemosyne/` |
|
|
| Mnemosyne (frontend) | `nexus/components/` |
|
|
| MemPalace | `nexus/mempalace/` |
|
|
| Scripts/tools | `bin/` |
|
|
| Git hooks/automation | `.githooks/` |
|
|
| Tests | `nexus/mnemosyne/tests/` |
|
|
|
|
**Never** create a duplicate module at the repo root (e.g., `mnemosyne/` when `nexus/mnemosyne/` already exists). Check `FEATURES.yaml` manifests for the canonical path.
|
|
|
|
---
|
|
|
|
## Feature Manifests
|
|
|
|
Each major module maintains a `FEATURES.yaml` manifest that declares:
|
|
- What exists (status: `shipped`)
|
|
- What's in progress (status: `in-progress`, with assignee)
|
|
- What's planned (status: `planned`)
|
|
|
|
**Check the manifest before creating new PRs.** If your feature is already shipped, you're duplicating work. If it's in-progress by someone else, coordinate.
|
|
|
|
Current manifests:
|
|
- [`nexus/mnemosyne/FEATURES.yaml`](nexus/mnemosyne/FEATURES.yaml)
|
|
|
|
---
|
|
|
|
## Workflow
|
|
|
|
1. Check the issue is unassigned → self-assign
|
|
2. Check `FEATURES.yaml` for the relevant module
|
|
3. Create feature branch from `main`
|
|
4. Submit PR with clear description and `Closes #NNN`
|
|
5. Wait for reviewer approval
|
|
6. Rebase if needed, then merge
|
|
|
|
### Emergency Exceptions
|
|
|
|
Hotfixes require:
|
|
- ✅ @Timmy approval
|
|
- ✅ Post-merge documentation
|
|
- ✅ Follow-up PR for full review
|
|
|
|
---
|
|
|
|
## Stale PR Policy
|
|
|
|
A cron job runs every 6 hours and auto-closes PRs that are:
|
|
1. **Conflicted** (not mergeable)
|
|
2. **Superseded** by a merged PR that closes the same issue or implements the same feature
|
|
|
|
Closed PRs receive a comment explaining which PR superseded them. If your PR was auto-closed but contains unique work, reopen it, rebase against `main`, and update the feature manifest.
|
|
|
|
---
|
|
|
|
## CI/CD Requirements
|
|
|
|
All main branch merges require (where applicable):
|
|
- ✅ Linting
|
|
- ✅ Unit tests
|
|
- ⚠️ Integration tests (pending for the-nexus, see #915)
|
|
- ✅ Security scans
|