Maintainer Guidelines¶
Release Procedure¶
To generate a new release:
-
Bump the version number in
pyproject.toml. -
Write the release notes from the commits since the last release (e.g.
git log v0.20.0..HEAD) in a newdocs/change_log/vX.Y.Z.md, and add it with its date to the nav inzensical.toml. -
Confirm all tests pass using the pre-built database. If they don't, generate a new one (
prebuildsaves a date-stamped zip, e.g.prebuild-2022-07-05.zip, to~/simmate/sqlite-prebuilds/). If only migrations have changed, start from the current prebuild:To reload all third-party data instead:simmate database reset --confirm-delete --use-prebuilt # also applies new migrations simmate database prebuildThen upload the newest zip tosimmate database reset --confirm-delete --no-use-prebuilt simmate database load <app_name> # repeat for each app simmate database prebuildsqlite-prebuilds/on the Simmate CDN (requiressettings.s3with write access) and updatearchive_filenameinsimmate.database.utils.load_default_sqlite3_build:simmate database upload-prebuild -
Create a release on GitHub, which automatically publishes to PyPI.
-
For the conda release, wait for the autotick bot to open a pull request on the simmate feedstock. Check its status here (under "Queued").
-
Review the autotick bot's changes before merging. Changes to dependencies will likely require manual updates.
-
After merging, wait for the conda-forge channels to update their indexes (about 30 minutes). Then, test the conda install:
conda create -n my_env -c conda-forge simmate -y
Desktop App Builds¶
PyInstaller can only build for the OS it runs on, so the desktop app is built and uploaded separately on each OS. This requires settings.s3 to be configured with write access to the Simmate CDN bucket. Uploads are named with the installed Simmate version, so update the version number (step 1 above) before building for a new release. On each machine:
uv sync --all-extras
simmate desktop build
# launch dist/simmate-desktop (or dist/simmate-desktop.exe) to check it works
simmate desktop upload
Re-uploading the same version replaces that version's file. For example, the links for version 0.19.0 are:
- Windows:
https://assets.simmate.org/desktop/simmate-desktop-0.19.0-windows.exe - Linux:
https://assets.simmate.org/desktop/simmate-desktop-0.19.0-linux - macOS (untested):
https://assets.simmate.org/desktop/simmate-desktop-0.19.0-macos
On startup, packaged apps compare their version to the latest GitHub release and offer to download the matching build from these links into ~/simmate/desktop/. They only do so once that OS's build is uploaded, so upload builds for each OS soon after a release.
The builds are not code-signed, so Windows shows a SmartScreen warning ("More info → Run anyway") and macOS Gatekeeper blocks the app until it is allowed in System Settings → Privacy & Security.
Full Test Suite¶
Tests that require third-party programs (like VASP) are skipped by default, but the full suite should be run before each release:
-
Prerequisites:
- Linux with VASP and Bader installed
- A dev install with
mainchecked out - Default settings (clear any custom
~/simmateconfigs)
-
Confirm the default test suite passes:
simmate dev test -
Reset to the pre-built database and update it. This simulates a new user's database:
simmate database reset --confirm-delete --use-prebuilt simmate database update -
(Optional) VASP tests run with
mpirun -n 14 vasp_std > vasp.outby default. Change this insrc/simmate/workflows/test/test_all_workflow_runs.pyif needed. -
Run the full suite, which adds the VASP tests:
simmate dev test --fullTip
To watch the VASP runs, run only the workflow tests with logging enabled:
pytest src/simmate/workflows/test/test_all_workflow_runs.py -s -m "not blender" -
If all tests pass, continue with the release. Discard any edits from step 4.