Skip to content

Latest commit

 

History

History
67 lines (42 loc) · 3.61 KB

CONTRIBUTING.md

File metadata and controls

67 lines (42 loc) · 3.61 KB
Raw

Contributing to apiron

Thanks for taking the time to contribute to apiron! Before you submit your work, take some time to read through these guidelines. You should also read and follow the code of conduct.

Submitting a pull request

All apiron changes and releases are done with the dev branch. As such, when developing, please cut a branch from dev and open your pull request against dev. We squash commits when merging to dev, so it's okay if you have several commits within your pull request. That being said, please make sure your commit messages are clear so we can tell what's happening!

Commits

Pre-commit hooks

This project uses pre-commit to run checks on the code prior to a successful commit. Installing pre-commit and using its hooks can ease your development by uncovering issues earlier in the development life cycle.

Commit messages

We don't currently have a strict commit message convention, but here are a few guidelines:

  • Use the imperative, present tense: Add cat pictures rather than Added cat pictures or I added some cat pictures
  • No punctuation at the end of the message -- if you need to describe something at length, do it in the body of the commit message
  • If addressing a specific, open issue in full, prefix the commit message with the issue number and a colon [e.g. #12: Add even more cats]

Testing

apiron is thoroughly tested. Its current scope has let us reach 100% code coverage with fairly low effort, which may not always be possible. Nonetheless, when fixing a bug it is helpful to us that you add a failing test that your fix makes pass. If adding a new feature, it should also be thoroughly tested. This allows for easier refactoring to prove that nothing broke in transit!

To test apiron, check out the repository and ensure the Python versions you would like to test are available on your $PATH as versioned executables like python3.10. Then, use tox to run the tests.

Code formatting

This project uses black for consistent code formatting. Before opening a pull request, try to remember to run black on your code; the build will fail otherwise. Note that black requires Python 3.6+ to run, although it supports formatting compatible with earlier versions of Python.

Release process

Setup

To participate in the release process, you'll need the following:

  • Accounts registered on Test PyPI and PyPI and added as maintainers of the apiron project
  • An account registered on Read the Docs and added as a maintainer of the apiron project
  • A virtual environment with tox installed, and any Python versions you want to test against available on your $PATH

Preparing a release

  1. Once all changes for a release are approved and incorporated into dev, update the pyproject.toml file to a new semantic version. Update CHANGELOG.md to reflect the new version and make sure all changes are reflected (see link in CHANGELOG.md for formatting).
  2. Open a pull request titled something like "v3.X.X release prep" and merge to dev
  3. Tag the head of dev as a new GitHub release matching the version in pyproject.toml, using the body of the version's changes from CHANGELOG.md as the release description
  4. Monitor the resulting actions to make sure the build artifacts are uploaded to PyPI and the GitHub release
  5. Smoke check the documentation build on Read the Docs