89 lines
2.9 KiB
Markdown
89 lines
2.9 KiB
Markdown
# Contributing to Serena
|
||
|
||
Serena is a governed refactor program for AUTOMATIC1111/stable-diffusion-webui. This guide helps you run verification locally and understand CI behavior.
|
||
|
||
---
|
||
|
||
## Quickstart
|
||
|
||
1. Install dependencies: `pip install -r requirements-test.txt` and runtime deps per `requirements_versions.txt`
|
||
2. Create stub repositories: `python scripts/dev/create_stub_repos.py`
|
||
3. Run tests: see [Local verification](#local-verification) below
|
||
|
||
---
|
||
|
||
## Local verification
|
||
|
||
To verify the project builds and tests pass without a real model:
|
||
|
||
```bash
|
||
python launch.py --skip-prepare-environment --skip-torch-cuda-test --exit
|
||
pytest test/smoke
|
||
```
|
||
|
||
For full CI parity (including server startup and API tests), start the test server in one terminal, then run pytest in another. See `.github/workflows/run_smoke_tests.yaml` for the exact commands CI uses.
|
||
|
||
**Test tiers:** `test/smoke` (fast, PR gate), `test/quality` (deeper unit tests), `test/nightly` (heavy tests). Run `pytest test` for the full suite.
|
||
|
||
---
|
||
|
||
## CI parity
|
||
|
||
CI uses deterministic stub repositories and fake inference to avoid external clones and real model loading. To reproduce CI locally:
|
||
|
||
1. Run `python scripts/dev/create_stub_repos.py` before any launch or test
|
||
2. Use `--skip-prepare-environment` when launching
|
||
3. CI sets `CI=true` (GitHub Actions default); txt2img/img2img return a deterministic 1×1 PNG in CI instead of invoking the model
|
||
|
||
---
|
||
|
||
## Stub repositories
|
||
|
||
CI uses stub repositories to satisfy import paths without cloning large external repos (e.g. ldm, sgm). See `scripts/dev/create_stub_repos.py` for implementation. The script creates minimal placeholder modules so the application can start and API contract tests can run.
|
||
|
||
---
|
||
|
||
## Development workflow
|
||
|
||
1. Create a branch from `main`
|
||
2. Make changes; run `ruff .` and `pytest test` locally
|
||
3. Open a PR targeting `m-cahill/serena:main`; CI runs linter, tests, and coverage
|
||
4. Do not push directly to `main`; merge via PR after CI passes
|
||
|
||
For milestone-specific workflow, see `docs/serena.md` and `docs/milestones/`.
|
||
|
||
---
|
||
|
||
## Serena repository workflow
|
||
|
||
Serena operates as an **independent governed fork** of AUTOMATIC1111/stable-diffusion-webui. The upstream repository is used only as a **reference baseline** for audit comparisons.
|
||
|
||
All development must occur within the Serena repository (`m-cahill/serena`).
|
||
|
||
**Correct PR flow:**
|
||
|
||
```
|
||
feature-branch → PR → m-cahill/serena:main
|
||
```
|
||
|
||
**Incorrect PR flow (never do this):**
|
||
|
||
```
|
||
m-cahill/serena → AUTOMATIC1111/stable-diffusion-webui
|
||
```
|
||
|
||
Upstream PRs must never be opened. CI includes a guardrail that fails if workflows run outside `m-cahill/serena`.
|
||
|
||
---
|
||
|
||
## Pre-push hook (optional)
|
||
|
||
To prevent accidentally pushing to upstream or other non-Serena remotes, install the pre-push hook:
|
||
|
||
```bash
|
||
cp scripts/dev/prevent_upstream_push.sh .git/hooks/pre-push
|
||
chmod +x .git/hooks/pre-push
|
||
```
|
||
|
||
The hook aborts the push if the target remote URL does not contain `m-cahill/serena`.
|