Contributing to LabFrog

Use this guide for code, docs, benchmark, and operational changes.

Before You Start

• Read the documentation hub at labfrog.readthedocs.io.

• Search the existing issue tracker before opening a new issue.

• Use the develop branch as the base for new work.

Documentation Policy

• Published docs are built from the doc/ folder.

• Keep README.md as a short intro and pointer page.

• Put substantive documentation updates in doc/ pages instead of expanding README.

Recommended Workflow

1. Pick or open an issue.

2. Create a branch from develop.

3. Make the change.

4. Run the checks that match the scope of your change.

5. Open a merge request targeting develop, link the issue, and list the checks you ran.

Example branch setup:

git checkout develop
git checkout -b feature/your-feature-name

Validation

Testing is the canonical command and test-ownership reference. Choose the smallest useful focused test first, then run the matching gate:

• uv run poe prepush-fast for routine code or documentation changes.

• uv run poe prepush-full for browser-facing or documentation-build changes.

• uv run poe build_docs plus visual review when screenshots should change.

• git diff --check before every handoff.

Use Benchmarks and Runtime Performance for performance runners and stored-result interpretation. pyproject.toml remains the source of truth for Poe task definitions and dependency groups.

Test Coverage Map

Use this generated map as a quick sense of which workflows are well covered before changing a shared route or template. Percentages come from the latest poe test-fast pytest-cov JSON run.

Overall labfrog line coverage from that run: 80.00%.

Area	Coverage	Main tests	Watch next
Startup, auth, and request state	71% Good	tests/test_app_factory.py, tests/test_public_routes.py, tests/test_helper_functions.py, tests/test_route_health.py	Environment-specific branches and login provider edge cases
Add Entry / Edit Entry	83% Good	tests/test_tab_routes.py, tests/test_navigation_routes.py, tests/test_target_series.py, tests/test_webkit_forms.py, tests/test_form_save_integrity.py, tests/test_ui_layout_invariants.py, tests/test_copy_forward.py, tests/test_entry_save_failure.py, tests/test_shot_details_routes.py, tests/test_offline_resilience.py	Less common set-mode and shot-number backfeed branches
Search Records	80% Good	tests/test_search_form.py	Drag/resize-heavy browser behavior around plots
Select Fields / Organize Sections	86% Strong	tests/test_management_workflows.py, tests/test_section_headers_mode.py, tests/test_shot_day_grouping.py, tests/test_form_save_integrity.py, tests/test_form_save_fidelity.py, tests/test_ui_layout_invariants.py, tests/test_audit_layout_fields.py	Campaign-mapped layout resolution across paired shot/set modes
Parameters, diagnostics, and selectables	76% Good	tests/test_management_workflows.py, tests/test_phase1_regression.py, tests/test_custom_selectables.py, tests/test_mediawiki_selectables.py, tests/test_form_save_fidelity.py	Diagnostic preset detail round-trips and option de-duplication
Init, reset, and operator tooling	79% Good	tests/test_init_db.py, tests/test_dev_tasks.py, tests/test_kafka_listener.py, tests/test_kafka_integration.py, tests/test_scheduled_backup.py	Real-service integration branches

Coverage Commands

• uv run poe test-fast is the default local regression pass for routine work.

• uv run pytest tests/test_search_form.py is a good focused-run pattern. Swap in the module closest to the change.

• uv run pytest --cov-report=html --cov-report=term-missing creates the browsable line report and still prints missing lines in the terminal.

• uv run poe test-fast refreshes the generated coverage map when the pytest-cov JSON data changes.

Troubleshooting First Response

When a bug report says “not working”, use this sequence before deep refactors:

1. Reproduce on canonical routes (/add_entry, /edit_entry, /diagnostic_options).

2. Confirm whether failure is server-side or browser-only.

3. Run the smallest matching test module first.

4. If Add and Edit fail together, start in labfrog/request_state.py and labfrog/entry_route_common.py.

5. Keep compatibility aliases only as bridges; fix canonical behavior first.

Tooling Reference

pyproject.toml is the source of truth for Poe tasks, dependency groups, pytest coverage settings, and shared contributor commands. Prefer uv run poe ... commands from this file when they exist.

Use these rules of thumb:

• Run uv run poe doctor once for a new checkout or after changing local config. It checks core tools, local config files, optional browser tooling, and a test-safe app import.

• Run uv run poe prepush-fast for routine code or docs changes.

• Run uv run poe prepush-full for browser-facing changes, docs-build changes, or broader workflow edits.

• Use uv run poe build-docs-html for a side-effect-light docs build. Use uv run poe build_docs only when screenshots should be regenerated.

• Hermes mainly matters for release automation.

• pyproject.toml, CITATION.cff, codemeta.json, and doc/conf.py each carry the release version. Bump them together in the release preparation commit; a release where they disagree ships the wrong metadata.

Repository Control Files

These files keep collaboration predictable across Windows, Linux, editors, and CI.

File or path	What it does	Why it matters
.gitattributes	Tells Git how to treat files and line endings.	Prevents accidental CRLF/LF churn and binary-file corruption.
.editorconfig	Gives editors shared whitespace and encoding defaults.	Keeps saves from different IDEs consistent.
CODEOWNERS	Maps paths to likely reviewers in GitLab.	Helps merge requests reach the right people.
.git-blame-ignore-revs	Lists large cleanup commits that git blame should skip.	Keeps line history useful after formatting or rename passes.
.gitlab/merge_request_templates/	Provides the default merge request checklist.	Makes reviews more consistent.
.gitignore	Lists local/generated files that should stay out of Git.	Keeps caches, temp files, and machine-specific noise out of commits.
pyproject.toml	Defines dependencies, Poe tasks, pytest options, and contributor workflows.	It is the main entrypoint for shared commands.

If one of these files changes, treat it as a repo-policy change rather than an app-feature change.

Review And Ownership

• CODEOWNERS is used so GitLab can suggest reviewers for docs, app code, tests, and scripts.

• The merge request template keeps issue links and verification notes consistent.

• Keep merge requests small enough to review.

• Mention the checks you actually ran in the merge request description.

The best merge requests:

• explain the problem in one or two sentences

• link the related issue

• mention the checks you ran

• include docs updates when user-visible behavior changed

Help And Maintainers

Name	Role	Handle
Kristin Tippey	Lead developer and technical implementation	@tippey27
Hans-Peter Schlenvoigt	Project coordination and requirements	@hs5955

If you are unsure about workflow, environment setup, or scope, ask on the related issue first.

Conduct

Be constructive, direct, and respectful. If a collaboration problem needs escalation, contact a maintainer.