Skip to content

Developer Guide

Jump to bottom
Oliver Beckstein edited this page Sep 19, 2024 · 21 revisions

Overview over the development process of alchemlyb and alchemtest. (The developer guide is an evolving document. Please modify as necessary.)

Development

Development happens on the master branch. The master branch is supposed to be installable and produce correct results at any time. We therefore insist on merging code that is covered by tests to about 90% coverage level (i.e., 90% of the lines of code are exercised by tests).

Pull Request, Review, Merge Model

  • We use a Pull Request, Review, Merge model for code development with continuous integration: code can only be added to master through a PR. The PR has to pass
    • code review by another developer with write access to the repo
    • unit tests (all existing tests pass)
    • coverage testing (new code comes with tests to check the majority of its functionality)
  • For each PR, the whole test suite is run (on Travis CI). If your PR does not pass tests then it will typically not be accepted. Ask for help (ping other developers with @NAME mentioning them in the comments of your PR).
  • PRs are typically merged (or rebased onto master) but sometimes the developer in charge can also decide to squash all commits (especially when there are many incremental commits) in order to keep the history clean.

For more details see How to do PRs.

Contributing

Fork the repository and create a PR or, if you have write access to the repo, create a branch in the repo. Name the branch issue-XXX-SUMMARY where you typically reference an issue in the issue tracker and SUMMARY is a very short description, e.g., issue-10-Amber-parser (to reference issue #10).

Discuss all issues related to a PR in the comments to the PR.

As a new contributor, add yourself to the file AUTHORS.

Style Guide

We use black since PR #280 so you don't need to think too hard about Python code formatting.

For doc strings we follow the NumPy docstring standard.

Testing

We use pytest. We use fixtures to set up data for the tests.

Since PR #278, the parsing operations for non-parsing related unit tests are done at the conftest.py as a fixture and made available globally for all tests (see Issue #206 for additional details). Any additional operations should be made in the local test file.

New code should be covered to nearly 100% with tests.

Release management

Parts of the process are automated. Releasing requires setting a release git tag and creating a release from the tag in GitHub. Follow the steps below.

Tagging a release candidate

  • We use semantic versioning MAJOR.MINOR.PATCH (i.e., briefly, major revision changes whenever the API changes in backwards-incompatible manner, MINOR changes for new features, PATCH changes for fixes that correct functionality; as long as MAJOR == 0, we can break the API with increasing MINOR.)

  • Finalize CHANGES.

  • Releases are cut from the master branch and tagged with MAJOR.MINOR.PATCH.LABEL (note: the release tag determines the tag because we use versioneer, which obtains the release number from the git tag). Given that the same tag cannot be uploaded to pypi twice, we use LABEL to test the build and fix it if necessary (...rc1 > ...rc2). We do from the master branch for the PyPI release

    1. git tag <major>.<minor>.<patch>.rc1
    2. git push --tags

  • Note: the tags need to be pushed to GitHub with git push --tags. (You can add text to the releases on GitHub.)

  • This will automatically trigger a github action (named deploy) to use pypa's build tool to create a tarball and & pure Python wheel and upload it on testpypi

Test the package

  • Once uploaded to testpypi, please check locally that the build is working as intended. In a clean environment do:
    1. pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple alchemlyb=="version number"
    2. pip install pytest
    3. pip install https://github.com/alchemistry/alchemtest/archive/master.zip
    4. pytest --pyargs alchemlyb
  • If the package test fails, solve the problem and try building the package locally (python -m build with build) and install the local package for testing. Once you fixed the problem, reupload it to testpypi with a new label (...rc2) and repeat the test process.

Note

For Mac with Apple Chip, the Jax installed with pip would not work. One needs to install Conda Jax before step 4. conda install jax

PyPi release

  • After a successful test of the testpypi package, create a new tag <major>.<minor>.<patch> and do a final testing on testpypi. Then create a release on GitHub; zenodo DOIs and snapshots are automatically minted.
  • The release will trigger the deploy action again, which will this time upload the tarball and wheel to PyPI.

Conda package

Conda packages are released on conda-forge.

Make a release on PyPi and wait for the regrocf autobot to open a PR on the feedstock. If there are no problems, the bot will auto-merge and the conda package will be built. (This can take up to 24h.) If there are issues, review, fix, and then and manually merge the PR.

Clone this wiki locally