Publishing ldcon

Public repository: FanHarvard/ldcon. Current version: 0.2.2. No production service is activated by publication.

One-time PyPI setup

A PyPI account owner creates a pending publisher at PyPI publishing settings with:

Use the repository's pypi environment to restrict release access. Authentication uses GitHub OIDC and PyPI Trusted Publishing; no long-lived PyPI API token belongs in this repository. See the official PyPI setup.

Updating an installation

In the virtual environment used for the installation:

python -m pip install --upgrade "ldcon[web,instruments,analysis,agents]"
python -m pip check

This selects the latest LDCon release and its declared compatible dependencies. LDCon pins experiment-core and fanharvard-agentbridge versions, so independent updates to those projects are adopted when the LDCon dependency pins are updated. For standalone use, update either with python -m pip install --upgrade experiment-core or python -m pip install --upgrade fanharvard-agentbridge.

Updating a Python environment does not promote an immutable production release or restart a service. The existing production installation uses its separate deployment and handover procedure.

Updating GitHub

Edit the public checkout, commit reviewed files and push to main. README and icon changes are visible on GitHub after the push; they do not require a PyPI version bump. The icon source is docs/icon.svg; regenerate its PNG with:

rsvg-convert --width 512 --height 512 --output docs/icon.png docs/icon.svg

The public checkout was split from the internal deployment repository. They do not synchronize automatically. Port reviewed source changes and test fixtures explicitly; export deployment configurations as disabled, sanitized examples. Preserve the public packaging metadata and exclude credentials, inboxes and runtime state instead of copying the full deployment directory or its Git history.

Publishing a new PyPI version

Change project.version in pyproject.toml to a new, unused version. Publish updated experiment-core or agentbridge dependencies first if needed. When changing the experiment-core pin, update its checkout tag in both CI and release workflows too.

From a development environment with the build, test and role dependencies installed, build into an empty directory so old distributions cannot be uploaded accidentally:

release_dir=$(mktemp -d)
python -m build --outdir "$release_dir"
python -m twine check --strict "$release_dir"/*
python scripts/check_dist.py "$release_dir"
python scripts/check_secrets.py
python -m pip install --force-reinstall --no-deps "$release_dir"/*.whl
python -m pytest -q
python -m pip check

Commit and push the reviewed changes. After CI succeeds, create a tag matching the new version (vX.Y.Z) and publish a GitHub Release for it. That runs release.yml; alternatively dispatch that workflow at the tag. The workflow checks the tag against package metadata, builds and audits distributions, tests the wheel, and publishes through the dedicated environment. Do not reuse an uploaded PyPI version. The CI workflow also checks Python 3.10, 3.12 and 3.13. An existing PyPI release's embedded README changes only with a new package version; a GitHub push alone does not replace it.

Site configuration

FanHarvard deployment configuration and clone/install procedures live in ldcon-fanharvard. That repository pins published packages; it does not vendor this library. Credential values and runtime state stay local.

Public/private boundary

Public: source, tests, documentation, MIT license and reviewed examples. Private: credentials, .env/.pypirc files, runtime databases, job logs, agent conversations, approval receipts, local deployment history and live service configuration. New public repositories start from a reviewed snapshot; the internal Git history is not uploaded.

The secret scanner compares findings against individually reviewed non-secret fixtures and code literals in .secrets.baseline. New findings fail CI. This complements artifact inspection; it is not a proof that arbitrary future data is safe to publish.