OpenSensation™
Documentation/Maintainers

Maintainer operations

Review a contribution

Check entity scope, stable ID, file location, unit/quantity pairing, species/device scope and whether evidence supports the exact claim. Inspect citations manually. Verify that context examples remain illustrative. Check contributor consent and conflicts; do not publish private credential documents. Preserve disagreement in review records and Git history.

Run canonical validation, pytest, Ruff, mypy, graph export and a Docker build. CI also exercises a PostgreSQL migration/import round trip. Review generated schema changes alongside typed code changes. Never mark claims expert-reviewed merely because a pull request passed code review.

Release

  1. Update software, dataset and schema versions independently as warranted. Software is declared in pyproject.toml and app/core/config.py; dataset defaults/configuration must agree with the release.
  2. Write a changelog with additions, relationship/evidence changes, breaking changes and deprecations.
  3. Pin dependency changes, review advisories and rebuild the container.
  4. Set the source commit in the release environment; validate and generate exports.
  5. Tag the reviewed commit. The workflow creates a draft release and checksum manifest.
  6. Inspect release assets and publish the draft when ready. Back up the database before migrations.
  7. Migrate a dedicated database, import canonical data, verify /health, /v1/meta, representative API/explorer routes and download hashes.
  8. Optionally sync Neo4j and verify known nodes/edges. This is a separate derived projection.

Commands

python -m alembic upgrade head
python -m scripts.import_data
python -m scripts.export_dataset
python -m scripts.export_graph
# Optional, with credentials:
python -m scripts.sync_graph

Do not run the seed authoring script on an existing canonical dataset. Idempotent import is the release path. Import removes stale records from the dedicated projection atomically; preserve old releases in Git and release archives.

Rollback and schema evolution

Re-importing a previous canonical release restores its data projection. Set its matching dataset version and source commit. For schema changes, test upgrade and downgrade on an isolated database and inspect destructive effects. Restore a known backup rather than attempting an unreviewed destructive downgrade. The initial downgrade removes all projection tables.

Prefer additive schema changes; deprecate fields and IDs with migration notes before removal. Regenerate JSON Schema and test old/new fixtures. Semantic changes can break research workflows even when JSON shape stays the same, so document them explicitly.

Operational ownership

Before public launch, configure actual CODEOWNERS, private security reporting, repository URL, cloud secrets, DNS/TLS, backups, edge limits and log retention. The code cannot make these account-level decisions automatically. Monitor database pool usage, errors and readiness. Keep secrets out of exception messages, query strings and logs.