Skip to content

Latest commit

 

History

History
313 lines (240 loc) · 13.4 KB

development.md

File metadata and controls

313 lines (240 loc) · 13.4 KB

Development and maintenance

Everything needed to work on the database, the tooling, and the SimHub client. For using As Driven, see the README and docs/install.md. For what makes a claim acceptable evidence, see CONTRIBUTING.md.

Python 3.11 or newer is the only requirement for the database side. The SimHub client additionally needs Windows and a local SimHub installation.

Repository layout

schema/v1/                   JSON Schemas for records, sources, and the index
data/v1/index.json           Dataset release manifest
data/v1/sources.json         Reusable provenance/source records
data/v1/archetypes.json      Named control mechanisms records classify against
data/v1/cars/*.json          One curated car record per file
curation/                    Explicit, reviewable promotion approvals
as_driven_db/                Dependency-free validator and staging importers
as_driven_db/site.py         Renders the database as one browsable page
research/                    Checked-in research manifests and generators
tests/                       Unit tests and small source-layout fixtures
simhub/AsDriven.Core/        Exact-match JSON reader and guidance logic
simhub/AsDriven.Plugin/      SimHub adapter and settings UI
simhub/dash/                 Generated Dash Studio source and raster assets
release/                     Independent database and client release packaging
docs/                        Data model, evidence, coverage, and process docs

Generated build/, dist/, bin/, obj/, Python caches, and local telemetry artifacts are ignored and must never be committed.

Required validation

After data, schema, Python tooling, research-manifest, or importer changes:

python -m as_driven_db validate
python -m unittest discover -s tests -v

After C#, SimHub adapter, settings, XAML, dashboard, overlay, or plugin asset changes:

powershell -NoProfile -ExecutionPolicy Bypass -File .\simhub\build.ps1

The public catalog's browser behavior is covered with Playwright. Install its test dependency once, then run the suite after changing site interaction:

npm ci
npx playwright install chromium
npm run test:site-browser

It exercises simulator deep links, conflicting filters, keyboard tabs, live result announcements, empty states, and a mobile-width layout. CI installs its own browser and runs the same suite.

The validation workflow also deploys the public catalog. Pull requests run all checks without deployment permissions. Pushes to main and manual runs on main deploy only after data validation, database packaging, core-client tests, and browser tests pass. Pages receives the build/site files exercised by Playwright, without rebuilding the site or repeating its tests in a separate workflow. Python tests run once on Linux and once through Windows database packaging, preserving platform-specific coverage. Standalone packaging commands still run their own checks by default.

The SimHub build expects SimHub at C:\Program Files (x86)\SimHub unless -SimHubInstallPath is supplied. It compiles, runs the .NET assertions, generates dashboards, and packages only under simhub/dist. It never installs into SimHub - installation is always a separate, explicit act.

Before committing:

git diff --check

Key documents

Document What it covers
data-model.md Field semantics, confidence policy, identity rules
evidence-boundaries.md Real, simulated, and effective guidance layers
verification-observations.md The guided in-game verification contract
contribution-intake.md Public submission, privacy, and intake states
maintainer-review-workflow.md Case contract and review states
registering-a-simulator.md The ten places a new simulator touches
archetypes.md Named control mechanisms and classification
importers.md AMS2 and iRacing import/review design
releasing.md Build, QA, and publishing process
architecture.md How the pieces fit together
simhub-roadmap.md Reference-client design and remaining work

Contribution review workflow

An assistant can prepare contributions using the CLI; the workbench offers another view of the same cases. Run both from the main checkout so they share its ignored build/review-cases queue. Routine research and proposal preparation do not require a separate worktree. See the maintainer workflow.

To open the workbench:

python -m as_driven_db review-submissions workbench

It opens the queue on localhost, exposes the durable case artifacts, accepts completed research JSON, and keeps promotion and GitHub publication behind separate explicit approval controls.

The same workflow from the CLI

Synchronize every open GitHub issue labeled contribution. Simulator- observation issues download their one attached JSON through the authenticated GitHub CLI and run intake and staging together. Existing-car research issues resolve the named curated record exactly and enter the amendment workflow without inventing an observation. Both create an idempotent case under ignored build/review-cases/:

python -m as_driven_db review-submissions sync
python -m as_driven_db review-submissions queue

Use sync --issue 42 for one issue. These commands require an authenticated GitHub CLI (gh auth login) and never change issue labels or comments.

Generate provider-independent research packets, then validate and attach a completed structured result:

python -m as_driven_db review-submissions research-brief
python -m as_driven_db review-submissions import-research 42 completed-research.json

Research can propose identity, sources, and field-level findings, but these commands cannot register a source, edit curated data, or promote a record.

Generate a schema-validated preview and dry run, review its final-review.md, then cross the separate explicit maintainer gate:

python -m as_driven_db review-submissions prepare-review 42
python -m as_driven_db review-submissions promote 42 --approve
python -m as_driven_db review-submissions finalize-release --test
python -m as_driven_db review-submissions publish-result 42

Approval refuses release-version drift, source-id drift, duplicate promotion, and any case that has not reached manifest-review. It registers approved candidate sources, allocates the next numbered review batch, promotes the record and approval, and marks the local case promoted.

finalize-release refreshes the AMS2 coverage manifest when local coverage inputs are available, otherwise retains its checked-in inventory snapshot. It also regenerates the cross-simulator disagreement audit, refreshes the generated README coverage block from the actual records, rebuilds the offline site, and validates the repository. Pass --test to include the full Python test suite.

After the release commit is pushed, publish-result previews the exact contributor-facing comment and close reason. It makes no GitHub change unless rerun with --approve, and refuses while tracked release files are dirty, the branch is ahead of its upstream, or finalization artifacts are stale.

Working with individual observations

Validate a draft exported by the plugin's guided verification form:

python -m as_driven_db validate-observation observation.json

Receive an untrusted public draft into the ignored local intake directory. This validates the strict schema, records a SHA-256 receipt, and distinguishes an exact resubmission from corroboration, contradiction, another implementation, or a new exact identity:

python -m as_driven_db intake-observation observation.json

Stage a curated-record candidate, then promote the reviewed bundle once identity and sources are resolved:

python -m as_driven_db import-observation observation.json --output build/staged.json
python -m as_driven_db promote-observation curation/review-batch.json

Audit records that still need real-world and simulator evidence separated:

python -m as_driven_db audit-boundaries --output build/evidence-boundaries.json

Browsing the database offline

One self-contained page, filterable by simulator, shifter, clutch, and blip, written to the ignored dist/ directory:

python -m research.build_simulator_disagreement_audit
python -m as_driven_db build-site

Comparison modes show all cars, multi-simulator coverage, or only conflicting established values; an unknown in one simulator never counts as disagreement. A car stays one row while reviewed simulators appear as separate views inside it, each with a stable shareable link.

Bulk importers

These stage candidates only. They never modify data/, and they produce normalized values alongside the raw source values.

python -m as_driven_db import-ams2 ams2.csv --output build/ams2-candidates.json
python -m as_driven_db import-iracing iracing.html --output build/iracing-candidates.json

Compare AMS2 candidates with identities already observed by SimHub:

python -m as_driven_db audit-simhub-ams2 --candidates build/ams2-candidates.json --cars-dir "C:\Program Files (x86)\SimHub\PluginsData\Automobilista2\Cars" --output build/ams2-simhub-identity-audit.json --review-csv build/ams2-alias-review.csv

Promote only the aliases recorded in a reviewed approval manifest:

python -m as_driven_db promote-ams2 --candidates build/ams2-candidates.json --audit build/ams2-simhub-identity-audit.json --approvals curation/ams2-approved-records.json --data-dir data/v1

A person must still resolve identity, review source metadata and reuse rights, and approve each promoted record.

Release commands

Build a database-only package:

powershell -NoProfile -ExecutionPolicy Bypass -File .\release\build-database.ps1

Build the complete release candidates on Windows with the SimHub SDK installed:

powershell -NoProfile -ExecutionPolicy Bypass -File .\release\build-release.ps1

This runs database validation, the Python tests, the complete SimHub build, temporary install and uninstall tests, database rollback tests, final-ZIP checksum and per-file hash verification, and an install from the extracted artifact. Outputs go under ignored dist/release.

Plugin and database versions describe different things, but ship together:

  • plugin and core DLL versions are aligned for an easily audited client build;
  • data/v1/index.json owns the dataset version;
  • every published release ships the full client package carrying the current dataset, so a release that exists only because the data changed still bumps the plugin version.

Users have exactly one update procedure: install the newest release over the old one. build-database.ps1 still produces a portable dataset package for clients that are not SimHub, and install-database.ps1 remains a maintainer tool - it resolves paths from a repository checkout and is not shipped to users.

See releasing.md and release/README.md before publishing.

Data versioning

  • schema_version follows semantic versioning and describes structure.
  • dataset_version follows semantic versioning and describes a curated data release.
  • verified_game_version belongs to every simulator entry. It says when that implementation was last checked; it does not claim newer game versions are equivalent.
  • Breaking schema changes create a new directory such as schema/v2 and data/v2. Existing releases remain readable.

README screenshots

The README shows five captures under docs/images/: preflight-card.png, preflight-card-compact.png, settings-garage.png, settings-browser.png, and guided-drive.jpg. All are from AMS2 1.6.9.91. settings-garage.png, settings-browser.png, and guided-drive.jpg were retaken for plugin 0.21.3 on dataset 0.5.49; the two pre-flight cards are still the plugin 0.21.0 captures on dataset 0.5.34. That is still fine, though for a narrower reason since 0.22.0: the card grew a state that draws convention guidance in the note panel, and the Audi V8 quattro DTM in both captures has an established synchromesh gearbox, so no rule reaches it and the card draws exactly as it did. Retake them against a car that carries guidance if you want that state on show. Say which build a capture came from when you replace one, because the set drifts apart otherwise.

If you replace one, keep it PNG, keep it under a few hundred kilobytes, and prefer a car whose technique is worth showing: the current pair use the Audi V8 quattro DTM because a synchromesh H-pattern exercises every field at once, and the browser capture uses the BMW 2002 Turbo for the same reason.

A photographic capture - anything showing the cockpit rather than the plugin's own flat UI - compresses badly as PNG. The first guided-drive.jpg was 235 KB as JPEG and 1.4 MB as PNG, for the same picture, with no visible loss on the overlay text that carries the meaning. Save cockpit captures as JPEG. The flat UI captures stay PNG, where it is the better format. The current set costs 315 KB for the cockpit JPEG and under 145 KB for each PNG.