Development

Use this page as the contributor entry point. Detailed maintenance references remain available without dominating the primary reader navigation.

Setup

uv sync
uv run poe doctor

The application factory is labfrog:create_app(). Local development normally uses AUTH_METHOD = "none", a disposable database, and external integrations disabled unless the change specifically concerns them.

Workflow And Validation

  • Contributing owns branch, review, documentation, licensing, and collaboration policy.

  • Testing owns validation commands, focused test routing, coverage, and optional browser/Kafka checks.

  • Runtime Performance owns guardrails and benchmark interpretation.

Choose focused tests first, then run the repository gate appropriate to the change. Use uv run poe build_docs only when screenshots should be refreshed; otherwise prefer the side-effect-light HTML build.

Architecture And Diagnosis

System Architecture and Developer Map is the canonical maintainer reference for request flow, module ownership, critical invariants, session and persistence boundaries, data contracts, shot-day grouping, and symptom-based diagnosis.

The short version is:

  1. labfrog/__init__.py loads configuration and registers blueprints.

  2. Routes resolve request and session context.

  3. request_state.py and form_factory.py construct a fresh runtime form.

  4. Templates and static JavaScript render the browser workflow.

  5. db.py and focused helpers own persistence behavior.

If Add Entry and Edit Entry fail together, inspect their shared request-state, form-building, and submission layers before changing both routes.

Compatibility And Internal Reference

  • Use feature-named canonical routes in new code.

  • Treat /tab* paths and broad helper_functions.py re-exports as migration surfaces, not preferred APIs.

  • Put new helper logic in the owning labfrog/helpers/ module.

  • Keep stored-record changes compatible with SQLite/NeXus export and DAMNIT.

See Legacy Deprecations for active aliases. The Internal Module Reference documents implementation modules; it does not make every listed function a stable external API.

Releases

CHANGELOG.md is the record; the GitLab release page is generated from it, so write the entry before tagging. Cutting a release is four steps:

  1. Add the ## [X.Y.Z] - YYYY-MM-DD section to CHANGELOG.md, and add its compare link at the foot of the file.

  2. Bump the version in pyproject.toml, CITATION.cff, codemeta.json, and the doc/conf.py fallback, then re-lock with uv lock. CI runs uv sync --frozen and rejects a stale lockfile. Miss one and the release ships metadata that disagrees with itself: codemeta.json stayed at 0.9.0 through both 0.9.1 and 0.9.2.

  3. Preview what will be published: uv run python scripts/changelog_section.py vX.Y.Z

  4. Tag it annotated and push: git tag -a vX.Y.Z -m "LabFrog vX.Y.Z: <summary>" then git push origin vX.Y.Z.

Pushing a tag matching vMAJOR.MINOR.PATCH runs prepare-release-notes and release, which publish the GitLab release using that changelog section as the description and the tag’s own subject line as the title. Any other tag is ignored, and a version with no changelog entry fails the pipeline rather than publishing an empty release page. Nothing else runs on a tag: documentation follows branches, and Read the Docs is the canonical host.

Maintainer References

  • Application Evolution Notes

  • Repository-level ROADMAP.md for current open work

  • scripts/db/README.md for database maintenance

  • scripts/backup_mongodb_data/README.md for backup tooling