Contributing#

Note

This is a non-exhaustive list of best practices for contributing code, based on industry standards and our team’s experience.

As you code#

  1. Reduce cognitive overhead:

    1. Pick meaningful, descriptive variable names.

    2. Write docstrings (leverage AI!) and comments. To be used in the API documentation the docstring should follow the Google style guide: Google Python Style Guide.

    3. Follow the Python Zen – explicit is better than implicit, etc.

  2. Write tests.

As you commit#

  1. Keep commits as “one logical unit”. This means that each commit should be a set of related changes that accomplish one task, fix one bug, or implement one feature. Using an editor like VS Code or using GitHub Desktop can help you stage related changes together.

  2. Adhere to semantic commit conventions.

  3. Format & lint your code (make format).

  4. Submit a draft PR so people know you are working on this & can provide advice/feedback early on.

As you finalize a PR#

  1. Target production for public AtomWorks changes.

  2. Keep overall PR under <400 LOC (lines of code) (Rule of thumb: 500 LOC takes about 1h to review).

  3. Read and fill out the PR checklist.

As you review#

  1. Foster a positive review culture – we want to learn from each other. Be critical but kind.

  2. Practice light-weight code reviews. Submit something small to atomworks.io/atomworks.ml that fixes a bug / improves documentation / adds a tiny feature to practice this within the next 24h. (Can be less than 30min)

  3. Keep review time <1h and <500 LOC for focus.

Contributing to the documentation#

The external AtomWorks documentation is built using Sphinx and hosted on GitHub Pages. Aside from having AtomWorks and its dependencies installed, to build the documentation locally, you will need to install the documentation requirements:

uv pip install -r docs/docs_requirements.txt

To build the documentation, navigate to the docs directory and run:

make html

If you are new to Sphinx, please refer to the Sphinx documentation for guidance on writing and formatting documentation. All of the documentation is written in reStructuredText (reST) format. For more information on reST, see the reStructuredText Primer.

Other Resources#

PR Hygiene#

When contributing to this repository, please follow these steps:

  1. Clone the repository

  2. Create the development environment (see the Installation guide).

  3. Create a new branch for your changes. - Use the following convention to name your branch: <category>/<description>. Categories: feat, fix, hotfix, refactor, docs, perf. - Example: feat/support-rdkit-small-molecule

  4. Make and commit your changes on your new branch. - Run autoformatting tools (make format) before committing. - Use commit messages like <type>: <description>. Types: feat, fix, refactor, docs, chore, wip. - Example: git commit -m "docs: add contributing guidelines"

  5. Open a pull request to production and describe your changes.

  6. Wait for review and merge your changes.

Publishing a release#

Releases use the explicit version in pyproject.toml and a matching Git tag. Branch pushes and PR merges do not publish packages.

One-time repository setup:

  • Configure the PyPI atomworks Trusted Publisher: owner RosettaCommons, repository atomworks, workflow release_and_docs.yaml, environment pypi.

  • Protect the pypi environment with reviewer approval and allow version tags.

  • Keep GitHub Pages Source as Deploy from a branch, using gh-pages and / (root). The workflow preserves versioned pages on that branch.

For each release, merge the reviewed PRs, wait for CI on the final production commit, and confirm that project.version matches an unused tag and PyPI version. From a checkout whose origin is the public repository:

git fetch origin
git tag -a v3.0.1 origin/production -m "AtomWorks 3.0.1"
git push origin refs/tags/v3.0.1

The tag runs package checks, installed-wheel checks, scientific CPU tests on GitHub-hosted runners and the docs build. After they pass, approve pypi to publish the checked archives; subsequent jobs create the GitHub Release and deploy documentation. Verify a fresh pip install atomworks==3.0.1, aw --help and the versioned docs.

Prereleases follow the same process without replacing stable latest docs. Never move a published tag or reuse a published package version.