Development#

Setup#

$ git clone https://github.com/CaltechOpticalObservatories/gecko.git
$ cd gecko
$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install -e ".[dev]"

The dev extra installs pytest, ruff and tox.

Layout#

src/gecko/
├── cli.py        # argument parsing and the report / -init flows
├── config.py     # finding, creating and migrating configuration files
├── triage.py     # the Triagetools class that collects everything
└── triage.ini    # template copied by `gecko -init`
gecko             # launcher for running from a source checkout
tests/            # pytest suite
docs/             # this documentation (Sphinx + MyST Markdown)

Checks#

All checks run through tox:

Command

What it does

tox -e py312

Run the tests on one Python version (py38 to py312)

tox -e lint

ruff check

tox -e docs

Build the HTML docs into docs/_build/html. Warnings are errors

tox -e linkcheck

Check external links in the docs (not run in CI)

tox

Tests on every installed Python version, plus lint and docs

During development, pytest and ruff check src tests work directly in the virtual environment.

The tests never touch your real configuration. They point XDG_CONFIG_HOME and /etc/gecko at temporary directories, skip the 3-second CPU sample and disable screenshots.

Continuous integration#

.github/workflows/ci.yml

Tests on Python 3.8–3.12 and ruff, for every push to main and every pull request.

.github/workflows/docs.yml

Builds the docs for every pull request. On main it also publishes them to GitHub Pages at https://caltechopticalobservatories.github.io/gecko/.

Writing docs#

Pages are Markdown, parsed by MyST, with the Shibuya theme. The CLI reference is generated from gecko.cli.build_parser() and the API page from docstrings (Google style). Update those at the source rather than in the page.

Preview locally:

$ tox -e docs
$ python -m http.server -d docs/_build/html

Releasing#

  1. Update __version__ in src/gecko/__init__.py.

  2. Move the “Unreleased” notes in CHANGELOG.md under the new version.

  3. Merge to main, then tag: git tag v0.2.0 && git push origin v0.2.0.

Compatibility promises#

  • Python 3.8 is the minimum supported version. Don’t use newer syntax or standard-library APIs; CI catches most of this.

  • The legacy command line keeps working: gecko -u NAME -m MESSAGE and gecko -init/--initialize. New features can add options or subcommands, but must not break these.

  • Linux is the deployment target.

Roadmap#

These changes are planned for later releases:

Core cleanup

Run each step independently so one failure can’t stop the bundle. Bundle exactly the files from this run, keeping the log folder structure. Handle timezone-aware timestamps. Add size and age limits for copied logs and science files. Make the science sub-folders configurable.

Command line

Subcommands (gecko report, gecko init, gecko config show|validate) plus --no-email and --dry-run, with the legacy flags kept as aliases.

Desktop GUI

A PySide6 application with a simple operator view (name, message, run, progress, open folder) and a separate settings page.