Contributing

Include a reproducible example with each feature or fix. Describe the behavior, the method used, and any limits that affect the result.

Package development#

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev,md,preview]'
ruff format src tests examples scripts skills
ruff check src tests examples scripts skills
pytest
python -m build

GPU and hardware-export tests are marked gpu and should be run on a native GPU adapter. Some optional example-rendering scripts need ffmpeg and ffprobe (brew install ffmpeg on macOS). CPU checks can run with pytest -m "not gpu".

GitHub Actions runs CPU tests and linting on Ubuntu and Windows, then builds and installs the wheel in a clean environment. For rendering or animation changes, run the local GPU suite on Apple silicon or Windows/NVIDIA and inspect the output. Video checks decode frames with PyAV and do not require an FFmpeg executable. Windows symlink tests skip when Developer Mode or administrator privileges are unavailable. Record the setup and results in the validation report.

Documentation development#

The website uses Next.js static export, React, and Tailwind CSS. Website development requires Node 22 or later. The Python package has its own dependencies.

cd website
npm ci
npm run dev

Open http://localhost:3000/proteinmotion/. Edit Markdown in docs/ or the site components in website/. The complete NMR source is inserted directly from examples/nmr_regions.py at build time, so it stays in sync.

Before submitting:

npm run build
npm run check
npm run verify

The build exports static HTML into website/out/. PAGES_BASE_PATH defaults to /proteinmotion; set it to a different repository path (or an empty string for root hosting) when building for another deployment. Keep site metadata in website/lib/config.ts consistent with the final public URL.

npm run verify checks exported pages, internal links, fragment targets, and media references. Browser checks should cover desktop/mobile layout, search, code copying, video controls, and reduced motion.

Rendered documentation examples#

Short examples are defined in examples/docs_examples.py. Their marked code sections appear beside the rendered output in the guides. To update the clips and snippets, run:

python scripts/render_docs_examples.py

This requires a working GPU. The command renders 720p/60 fps clips, checks every encoded frame, saves posters, and updates the matching Markdown snippets. Run it before building the website. The build checks source, input, and media hashes to catch outdated previews.

Use output=<example-id> after the language in a Markdown code fence to pair a snippet with its clip. Existing gallery videos use output=gallery-<demo-id> beside their render commands.

Gallery examples#

The website gallery shows one short Studio scene per feature. Each scene is a runnable file in examples/gallery/, listed with its category, title, summary, search tags, and poster time in examples/gallery/catalog.json. To add an example, write the scene, add its catalog entry, and render it:

python scripts/render_gallery.py --only <example-id>

Run the script without --only to render every example. Clips are 1280 × 720 at 60 fps. An entry whose scene is a list of four scenes is tiled 2 × 2, for looks such as lighting presets that cannot change during a scene. The manifest records each scene's source and input hashes, and the website build rejects missing or outdated clips. Watch each new clip before committing it. Geometry that fades to full opacity, such as a base-style change or a density slice, can shift on the last frame of the transition, and a change of surface kind switches immediately.

Publishing#

The Pages workflow builds on pull requests and pushes. Only main pushes or a manual workflow run from main deploy. GitHub Pages must use GitHub Actions as its source. The workflow uploads the static export and deploys it with the official Pages actions. GitHub Pages serves the exported static files.

Compressed web previews are committed in website/public/media/. They are 720p versions of the original 1080p/60 fps films (the continuous tour retains 60 fps; other previews use 30 fps). Their source filenames and sizes are recorded in provenance.json; the scientific data provenance lives in the documentation. Original rendered videos, caches, local environments, and build outputs are ignored.

Changes and issues#

Open an issue with a minimal scene, input format, Python version, and the output of proteinmotion doctor. For rendering defects, include the relevant time or frame. Use a public example structure when reporting an issue in the public repository.

A pull request should explain the behavior change and relevant checks. Record the source of example data and distinguish deposited structures, simulated trajectories, and interpolated coordinates.

Package and skill releases#

The AI agent skill source is skills/proteinmotion-movies. Its six resource files are mapped into the wheel by pyproject.toml; keep that mapping in sync when adding a skill resource. Run the skill-creator validator when changing its instructions. The starter scene is shared by the skill and proteinmotion init, so maintain it once.

Build with python -m build (the wheel is built from the sdist). Install that wheel into a fresh environment, change out of the checkout, and run python -I /path/to/repo/scripts/check_installed_package.py --render on a native GPU. CI runs the same installed-resource check without rendering. Distribute the wheel, source archive, skill ZIP and checksums as versioned GitHub Release assets. Publish versioned release assets after the release checks pass.

PyPI publishing#

The publish.yml workflow builds the source archive and wheel, validates the PyPI description, and checks the installed wheel on Linux, Windows, and macOS. Linux installation checks cover Python 3.11–3.14. A manual run with publish left false performs these checks without uploading.

The PyPI project uses this GitHub Trusted Publisher:

The repository's pypi environment allows deployments from tags matching v*. Trusted Publishing authenticates each upload with GitHub's short-lived identity credentials. Maintain the publisher settings above when changing the workflow or repository.

For a release:

1. Update pyproject.toml, proteinmotion.__version__, and the website package version, then run python scripts/build_reference.py.
2. Run package checks, python -m build, and python -m twine check --strict dist/*. Verify an isolated installation and a native GPU render with scripts/check_installed_package.py --render.
3. Commit the release and create its matching v<version> tag. Publish a GitHub Release for that tag to start the PyPI workflow. The upload job requires the tag to match the package version and waits for all installation checks.
4. Confirm the version on PyPI, then install it with python -m pip install --index-url https://pypi.org/simple proteinmotion==<version> in a fresh environment.

A manual publishing run must select the version tag and set publish to true. PyPI distribution filenames are permanent: change the version for a corrected release instead of replacing files. Keep previous release artifacts in separate directories when building a new version.

Reference manual#

The manual reads signatures, defaults, inheritance, and source locations from the Python files. Descriptions and example links are maintained in docs/reference/catalog.json. After changing either, regenerate the reference data:

python3 scripts/build_reference.py

The generator uses Python’s standard library. The website build checks that the generated data matches the source and that every package export has a reference entry. Describe new parameters and methods in the catalog before building.