Skip to content

Artifact Policy

Gridalyn tracks source, contracts, tests, documentation, and one minimal demo dataset. It does not track generated simulation outputs, compiled documents, caches, heavyweight data, or publication workspaces.

Tracked

  • gridalyn/ source code;
  • dashboard source under dashboard/src/;
  • documentation source under docs/;
  • project manifests, workflow manifests, scripts, and README files;
  • tests and package configuration;
  • examples/tutorials/data/minimal/.

Not Tracked

  • projects/*/outputs/;
  • _build/, /site, and other compiled documentation outputs;
  • root cache/;
  • examples/generated/cache/ and examples/generated/outputs/;
  • generated instances/*/digital_twin/**/*.parquet files;
  • dashboard public generated data bundles;
  • publication drafts, presentations, review material, and working files;
  • LaTeX build outputs and compiled PDFs;
  • local caches, scratch files, node modules, and virtual environments.

Minimal Demo Dataset

The only demo data approved for Git is:

examples/tutorials/data/minimal/

The directory must stay below 10 MB. It should contain small inputs and compact expected summaries, not full study outputs.

Current contents:

  • manifest.json;
  • grid_nodes.geojson;
  • grid_edges.geojson;
  • buildings.geojson;
  • scenarios.json;
  • expected_summary.json.

Check the repository policy with:

uv run gridalyn platform check-artifacts --summary-only

Expected result for a healthy working tree: "valid": true.

Tutorial Samples

Tutorial inputs outside examples/tutorials/data/minimal/ should remain small, documented, and tied to a runnable example. New tutorials should either use the minimal dataset or declare an explicit project input under projects/<name>/inputs/.

Full Artifacts

Full digital-twin data, project outputs, and publication material should be regenerated by workflows or distributed later through releases, object storage, DVC, a separate publication repository, or a dedicated gridalyn project fetch-artifacts command. The default runtime instance lives under instances/default/digital_twin/. Additional runtime instances should use the same instances/<name>/digital_twin/ structure.

Baseline Procedure

Use this procedure only when maintainers intentionally create a fresh public baseline.

  1. Create an archive branch or tag for the current state.
  2. Create a clean orphan branch or a separate clean repository.
  3. Copy only tracked-policy files into the clean baseline.
  4. Run the hygiene tests and documentation build.
  5. Make the first clean commit:
git commit -m "Initialize Gridalyn platform baseline"

Do not run destructive repository commands without an explicit maintainer decision.