docs: add 11 new documentation files across all categories
New reference docs: - agents/ref-btmsg.md: inter-agent messaging schema and CLI - agents/ref-bttask.md: kanban task board operations - providers/ref-providers.md: Claude/Codex/Ollama/Aider comparison - config/ref-settings.md: (already committed) New guides: - contributing/dual-repo-workflow.md: community vs commercial repos - plugins/guide-developing.md: Web Worker sandbox API and publishing New pro docs: - pro/features/knowledge-base.md: persistent memory + symbol graph - pro/features/git-integration.md: context injection + branch policy - pro/marketplace/README.md: 13 plugins catalog Split files: - architecture/data-model.md: from architecture.md (schemas, layout) - production/hardening.md: from production.md (supervisor, sandbox, WAL) - production/features.md: from production.md (FTS5, plugins, secrets, audit)
This commit is contained in:
Hibryda
parent
8251321dac
commit
b6c1d4b6af
11 changed files with 2198 additions and 0 deletions
170
docs/contributing/dual-repo-workflow.md
Normal file
170
docs/contributing/dual-repo-workflow.md
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
# Dual-Repo Workflow
|
||||
|
||||
Agents Orchestrator uses a dual-repository model to maintain an open-source
|
||||
community edition alongside a private commercial edition.
|
||||
|
||||
## Repositories
|
||||
|
||||
| Remote | Repository | Visibility | Purpose |
|
||||
|--------|-----------|------------|---------|
|
||||
| `origin` | DexterFromLab/agent-orchestrator | Public (MIT) | Community edition |
|
||||
| `orchestrator` | agents-orchestrator/agents-orchestrator | Private | Commercial edition |
|
||||
|
||||
Both remotes are configured in every developer clone:
|
||||
|
||||
```
|
||||
$ git remote -v
|
||||
orchestrator git@github.com:agents-orchestrator/agents-orchestrator.git (fetch)
|
||||
orchestrator git@github.com:agents-orchestrator/agents-orchestrator.git (push)
|
||||
origin git@github.com:DexterFromLab/agent-orchestrator.git (fetch)
|
||||
origin no-push-to-community (push)
|
||||
```
|
||||
|
||||
Note: `origin` push URL is set to `no-push-to-community` -- a non-existent URL
|
||||
that causes `git push origin` to fail. This is intentional. All pushes go to
|
||||
`orchestrator`.
|
||||
|
||||
## Development flow
|
||||
|
||||
All daily development happens on the `orchestrator` remote. The community
|
||||
edition receives curated exports stripped of commercial code.
|
||||
|
||||
```
|
||||
Developer -> orchestrator (private) -> curated export -> origin (public)
|
||||
```
|
||||
|
||||
### Branch model
|
||||
|
||||
| Branch | Scope | Description |
|
||||
|--------|-------|-------------|
|
||||
| `main` | Shared | Community-safe code. Synced between both remotes. |
|
||||
| `hib_changes_v2` | Development | Active development branch on orchestrator. |
|
||||
| `commercial/*` | Pro-only | Features exclusive to the commercial edition. |
|
||||
|
||||
### Typical workflow
|
||||
|
||||
1. Create a feature branch from `main` on `orchestrator`.
|
||||
2. Develop and test.
|
||||
3. Push to `orchestrator` and open a PR against `main`.
|
||||
4. After merge, community sync happens via curated export.
|
||||
|
||||
## Syncing from community
|
||||
|
||||
To pull community contributions into the private repo:
|
||||
|
||||
```bash
|
||||
make sync
|
||||
```
|
||||
|
||||
This runs:
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git merge origin/main
|
||||
```
|
||||
|
||||
Resolve any conflicts between community contributions and commercial code.
|
||||
|
||||
## Leak prevention
|
||||
|
||||
Three layers prevent commercial code from reaching the public repository.
|
||||
|
||||
### 1. Git pre-push hook
|
||||
|
||||
`.githooks/pre-push` scans commits being pushed to any remote matching
|
||||
`DexterFromLab`. If any commit touches files in `agor-pro/` or
|
||||
`src/lib/commercial/`, the push is blocked:
|
||||
|
||||
```
|
||||
==========================================
|
||||
PUSH BLOCKED: Commercial code detected!
|
||||
==========================================
|
||||
|
||||
The following commercial files were found in commits being pushed:
|
||||
- agor-pro/src/billing.rs
|
||||
- src/lib/commercial/license.ts
|
||||
|
||||
You are pushing to the community remote (git@github.com:DexterFromLab/...).
|
||||
Commercial code must NOT be pushed to this remote.
|
||||
==========================================
|
||||
```
|
||||
|
||||
Enable the hook after cloning:
|
||||
|
||||
```bash
|
||||
make setup
|
||||
# or manually:
|
||||
git config core.hooksPath .githooks
|
||||
```
|
||||
|
||||
### 2. CI leak check
|
||||
|
||||
`.github/workflows/leak-check.yml` runs on every push and PR to `main` on the
|
||||
community repo. It fails the build if:
|
||||
|
||||
- `agor-pro/` directory exists
|
||||
- `src/lib/commercial/` contains files beyond `.gitkeep`
|
||||
- Any file contains `SPDX-License-Identifier: LicenseRef-Agor-Commercial`
|
||||
|
||||
### 3. SPDX headers
|
||||
|
||||
Commercial files carry an SPDX header identifying them:
|
||||
|
||||
```rust
|
||||
// SPDX-License-Identifier: LicenseRef-Agor-Commercial
|
||||
```
|
||||
|
||||
The CI leak check scans for this marker as a final safety net.
|
||||
|
||||
## File conventions
|
||||
|
||||
| Path | Edition | Description |
|
||||
|------|---------|-------------|
|
||||
| `agor-pro/` | Commercial | Pro Rust crate (billing, licensing, accounts) |
|
||||
| `src/lib/commercial/` | Commercial | Pro frontend components |
|
||||
| `src/lib/commercial/.gitkeep` | Community | Placeholder (no content) |
|
||||
| Everything else | Community | MIT-licensed code |
|
||||
|
||||
Commercial code is conditionally compiled:
|
||||
|
||||
- **Rust:** `#[cfg(feature = "pro")]` gates, Cargo feature flag
|
||||
- **Frontend:** `AGOR_EDITION` env var checked at test/build time
|
||||
|
||||
## Makefile targets
|
||||
|
||||
```bash
|
||||
make setup # Configure git hooks + npm install
|
||||
make build # Community build (cargo build + npm run build)
|
||||
make build-pro # Commercial build (cargo build --features pro)
|
||||
make test # Run all community tests (npm run test:all)
|
||||
make test-pro # Run commercial tests (cargo test --features pro + vitest)
|
||||
make sync # Pull community changes (git fetch origin + merge)
|
||||
make clean # Remove build artifacts (cargo clean + vite cache)
|
||||
```
|
||||
|
||||
### Building the commercial Tauri app
|
||||
|
||||
```bash
|
||||
cargo tauri build -- --features pro \
|
||||
--config src-tauri/tauri.conf.commercial.json
|
||||
```
|
||||
|
||||
This merges the commercial Tauri config (different bundle ID, product name,
|
||||
updater URL) with the base config and enables the `pro` Cargo feature.
|
||||
|
||||
## Adding commercial features
|
||||
|
||||
1. Place Rust code in `agor-pro/src/` or behind `#[cfg(feature = "pro")]`.
|
||||
2. Place frontend code in `src/lib/commercial/`.
|
||||
3. Add SPDX header to every new file.
|
||||
4. Test with `make test-pro`.
|
||||
5. Push to `orchestrator` only. Never push to `origin`.
|
||||
|
||||
## Removing commercial code for export
|
||||
|
||||
When preparing a community release:
|
||||
|
||||
1. Ensure `main` has no commercial file paths in its history.
|
||||
2. The `no-push-to-community` push URL and pre-push hook prevent accidents.
|
||||
3. If a commercial file is accidentally committed to `main`, rewrite history
|
||||
before any push to `origin`. Rotate any exposed secrets.
|
||||
Loading…
Add table
Add a link
Reference in a new issue