91 lines
3.0 KiB
Markdown
91 lines
3.0 KiB
Markdown
# Roo Code rules — enforce extensions (no legacy) and auto-migrate if detected
|
||
|
||
## 1. Hard mode: never run legacy
|
||
|
||
- Disallow any pipeline using `bl_info` packaging/installation.
|
||
- If no `blender_manifest.toml` exists, create it (see §3) and proceed as an **Extension** only.
|
||
- If both `bl_info` and `blender_manifest.toml` exist, ignore `bl_info`. Fail if any legacy pack/install step is attempted.
|
||
|
||
## 2. Detection and fail-fast
|
||
|
||
Treat as **legacy** if:
|
||
|
||
- Missing `blender_manifest.toml`, **or**
|
||
- Absolute intra-package imports (e.g., `import my_addon.module`), **or**
|
||
- External deps not vendored as wheels in `./wheels/`.
|
||
|
||
On detection → run §4 (migration). If migration can’t complete, fail with an actionable diff.
|
||
|
||
## 3. Required extension scaffold (write/update)
|
||
|
||
Create `blender_manifest.toml` at repo root:
|
||
|
||
```toml
|
||
schema_version = "1.0.0"
|
||
id = "<package_name>" # must equal the top-level package folder
|
||
version = "1.0.0"
|
||
name = "<Human Name>"
|
||
type = "add-on"
|
||
maintainer = "<Name> <email@example.com>"
|
||
blender_version_min = "4.2.0"
|
||
license = "GPL-3.0-or-later"
|
||
```
|
||
|
||
Rules:
|
||
|
||
- Single top-level Python package whose folder **equals** `id`.
|
||
- `AddonPreferences` live in the root package and must be visible via Extensions.
|
||
|
||
## 4. Auto-migration (legacy → extension)
|
||
|
||
1. Move metadata from `bl_info` → `blender_manifest.toml`; **remove** `bl_info`.
|
||
2. Convert absolute intra-package imports to **relative** (`from . import x`).
|
||
3. Vendor Python deps as wheels under `./wheels/` (platform-specific if needed).
|
||
4. Enforce layout:
|
||
|
||
```
|
||
<repo>/
|
||
├─ <id>/ # Python package
|
||
│ └─ __init__.py
|
||
├─ blender_manifest.toml
|
||
└─ wheels/ # optional, *.whl
|
||
```
|
||
|
||
5. Build only an **Extension** zip.
|
||
|
||
## 5. Build and install (extensions only)
|
||
|
||
- Use Blender’s Extension Builder/CLI to produce `id-version.zip`.
|
||
- Prohibit legacy zipping of parent directories.
|
||
- Install-test on a **clean** profile: Preferences → Extensions → Install from Disk; enable/disable must pass.
|
||
|
||
## 6. CI guardrails
|
||
|
||
- Lint manifest (keys, semver; `id == package folder`).
|
||
- Assert **no** `bl_info` remains.
|
||
- Block absolute intra-package imports.
|
||
- Verify wheels exist for any bundled deps.
|
||
- Headless smoke test: register → basic op → unregister without errors.
|
||
|
||
## 7. Preferences guarantee
|
||
|
||
- Define `bpy.types.AddonPreferences` in the root package with `bl_idname = __package__`.
|
||
- Must appear under **Edit → Preferences → Add-ons → [Your Add-on]**.
|
||
- Access pattern:
|
||
|
||
```python
|
||
prefs = bpy.context.preferences.addons[__package__].preferences
|
||
```
|
||
|
||
## 8. Failure messages (actionable)
|
||
|
||
- `Legacy detected: manifest created, imports converted, bl_info removed. Re-run build.`
|
||
- `Extension layout invalid: 'id' must equal package folder.`
|
||
- `Missing wheels: dependency X referenced but no wheel under ./wheels/.`
|
||
|
||
## 9. Explicitly blocked
|
||
|
||
- No dual artifacts (legacy + extension) from the same commit.
|
||
- No network installs or `pip` at runtime.
|
||
- Artifacts must be self-contained.
|