Developer Guide

Overview over the development process. (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.

Pull Request, Review, Merge Model

• We use a Pull Request, Review, Merge model for code development with continuous integration: code should 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) — we aim for >95% coverage.
• 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.

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

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

Release management

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

• 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:

  1. Finalize CHANGELOG
  2. git tag <major>.<minor>.<patch>
  3. Check that PyPi will be ok: twine check dist/pmda-0.3.0* (needs readme_renderer). If not, fix.
  4. git push && git push --tags (do both because Travis CI will not run if there's only a tag push)
  5. python setup.py sdist bdist_wheel
  6. twine upload dist/*
  7. conda-forge package: Either wait for the bot to create a PR for you or do the PR manually:
     1. Bot: after the package appeared on PyPi, look for an automatically generated PR in conda-forge/pmda-feedstock, review, merge.
     2. Manually:
        • Pull from upstream https://github.com/conda-forge/pmda-feedstock

          git pull https://github.com/conda-forge/pmda-feedstock master
          

        • rerender feedstock (conda smithy rerender)
        • Update meta.yml with <major>.<minor>.<patch> in https://github.com/MDAnalysis/pmda-feedstock, too, so that you don't forget (needed for conda release)
        • SHA256 of the tar.gz that will be uploaded to pypi: shasum -a 256 dist/pmda-0.2.0.tar.gz
        • reset build number to 0 if new release
        • update any dependencies
        • create a PR against upstream https://github.com/conda-forge/pmda-feedstock

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

• Packages are published from the tagged (pip package, conda package, tar balls on GitHub, zenodo).

  • pip: see above with twine
  • source tarballs on GitHub: create a release from the tag (just add some text)
  • conda: update meta.yml and and create a PR for the conda-forge repo. (follow instructions in MAINTAINER.md)
  • zenodo tarballs and DOIs are automatically minted

• Docs are managed on mdanalysis.org/pmda (only the latest develop) and update automatically.