Skip to content

developer guide

Jump to bottom
Oliver Beckstein edited this page Oct 18, 2022 · 1 revision

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

alchemtest and alchemlyb are developed in close cooperation.

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 almost 100% coverage level (i.e., 100% of the lines of code are exercised by tests). For alchemtest this primarily means that the test files can be found.

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. 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.

Contributing

See contributing.

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

  • 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.)

  • Note: alchemtest does not have a CHANGES file. (Finalize CHANGES)

  • Releases are cut from the master branch and tagged with MAJOR.MINOR.PATCH (note: the release tag determines the tag because we use versioneer, which obtains the release number from the git tag). We do from the master branch for the PyPI release

    1. git tag <major>.<minor>.<patch>
    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 alchemtest=="version number"
    2. pip install pytest
    3. pytest --pyargs alchemtest

PyPi release

  • After a successful test of the testpypi package, 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

Currently no conda packages availabl (Oct 2022).

Clone this wiki locally