mirror of
https://github.com/dtzp555-max/aci-sim.git
synced 2026-07-19 09:46:33 +00:00
taodengandClaude Fable 5
1d29a2f289
Clean-room README test found a newcomer hits failures in the first 5 min — all doc/script, not sim bugs. Fixes: - scripts/run.sh: use ./.venv/bin/python (was bare `python` → ModuleNotFoundError: uvicorn unless the venv was activated; now matches sandbox-up.sh). - NEW `aci-sim query CLASS [--dn/--host/--json]`: stdlib aaaLogin→cookie→query helper so newcomers don't hand-roll auth cookies (the old README smoke test `curl class/fabricNode.json` had no auth → returned an APIC error envelope). - README: 60-second quickstart + embedded topology screenshot (docs/images/ topology.png), port-mode leads with `aci-sim run`, smoke test uses `aci-sim query`, install notes git+https is package-only. 900 tests pass (+12 for aci-sim query). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
91 lines
3.9 KiB
Markdown
91 lines
3.9 KiB
Markdown
# Contributing to aci-sim
|
|
|
|
Thanks for considering a contribution. This project is a REST simulator, not
|
|
a production service, so the bar is: does it faithfully match real APIC/NDO
|
|
behavior, and does the test suite stay green.
|
|
|
|
## Dev setup
|
|
|
|
```bash
|
|
git clone https://github.com/dtzp555-max/aci-sim.git
|
|
cd aci-sim
|
|
python -m venv .venv
|
|
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
pip install -e '.[dev]' # installs aci_sim + fastapi/uvicorn/pydantic/pyyaml + httpx/pytest
|
|
```
|
|
|
|
## Running the tests
|
|
|
|
```bash
|
|
.venv/bin/python -m pytest -q
|
|
```
|
|
|
|
The suite currently has **900 tests** and must stay green. If you add a
|
|
feature or fix a bug, add or extend tests under `tests/` in the same PR —
|
|
most existing tests are organized by PR/feature (`tests/test_pr*.py`,
|
|
`tests/test_<feature>.py`); follow that convention for new ones.
|
|
|
|
`tests/verify_autoaci.py` (run via `scripts/verify.sh`) is a separate
|
|
verification harness that replays real ACI/NDO query patterns end-to-end
|
|
against a *running* sim instance — it's not part of the plain `pytest`
|
|
collection and isn't required for a normal PR, but it's worth running if
|
|
your change touches the query engine or the write path.
|
|
|
|
## Linting (informational only)
|
|
|
|
There's a `ruff` config in `pyproject.toml` (`[tool.ruff]`), and CI runs
|
|
`ruff check .` — but as a **non-blocking** job (see
|
|
`.github/workflows/ci.yml`'s `lint` job). There's a pre-existing baseline of
|
|
lint findings in the repo today; you don't need to fix unrelated ones in
|
|
your PR, but please don't add new ones in the code you touch.
|
|
|
|
```bash
|
|
.venv/bin/ruff check .
|
|
```
|
|
|
|
## `topology.yaml` drives everything
|
|
|
|
`topology.yaml` is the single source of truth for the whole simulated
|
|
fabric — sites, nodes, tenants, VRFs/BDs/EPGs, contracts, L3Outs, ISN,
|
|
seeded faults, and access-policy defaults. Every plane (both sites' APIC
|
|
stores and the NDO model) is derived from the *same* `Topology` object at
|
|
build time (`aci_sim/build/orchestrator.py`, `aci_sim/ndo/model.py`), which
|
|
is what keeps tenant/VRF/BD names and IDs consistent between a site's APIC
|
|
and NDO's view of it. If you're adding a new object or knob:
|
|
|
|
1. Add the field to `aci_sim/topology/schema.py` (Pydantic v2) — optional,
|
|
with a default that reproduces the pre-existing hardcoded behavior, so
|
|
existing `topology.yaml` files keep validating and building
|
|
byte-identical output.
|
|
2. Wire it into the relevant builder(s) under `aci_sim/build/`.
|
|
3. If it should show up in NDO's view too, wire it into `aci_sim/ndo/model.py`.
|
|
4. Run `aci-sim validate` against the repo's own `topology.yaml` and against
|
|
`aci-sim new`-generated topologies to confirm nothing regressed.
|
|
|
|
See `docs/DESIGN.md` for the module map and the design rationale behind
|
|
past additions, and `docs/CONTRACT.md` for the exact REST behavior contract
|
|
(error envelopes, query semantics, the object catalog) new code needs to
|
|
match.
|
|
|
|
## What PRs should (and shouldn't) do
|
|
|
|
- Keep `pytest -q` green — this is the actual acceptance bar, not a
|
|
suggestion.
|
|
- Prefer additive, backward-compatible changes to `topology.yaml`'s schema
|
|
(new optional fields with safe defaults) over changes that would break an
|
|
existing topology file.
|
|
- Match the existing code style — small, single-purpose builder functions,
|
|
docstrings that explain *why* (not just what), and tests that assert on
|
|
the exact REST response shape, not just "it didn't crash."
|
|
- **Do not reintroduce any real/customer data** — hostnames, IPs, tenant or
|
|
site names, credentials, or anything else identifying a real deployment.
|
|
This repo only uses generic placeholders (`LAB0`/`LAB1`/`LAB2`,
|
|
`App1`-`App5`, `MS-TN1`/`SF-TN1`, `10.192.x`/`10.10.x`, and similar) —
|
|
keep new examples, tests, and docs consistent with that convention.
|
|
|
|
## Filing issues
|
|
|
|
Bug reports are most useful with: the exact request (method + path + body)
|
|
that produced the wrong behavior, what you expected (ideally referencing
|
|
real APIC/NDO documented behavior), and what the sim actually returned.
|