Contributing

Contributions to this repository are welcomed and encouraged.

Code Contribution

This project uses the GitHub Flow model for code contributions. Follow these steps:

  1. Create a fork of the upstream repository at lubianat/wdcuration on your GitHub account (or in one of your organizations)
  2. Clone your fork with git clone https://github.com/<your namespace here>/wdcuration.git
  3. Make and commit changes to your fork with git commit
  4. Push changes to your fork with git push
  5. Repeat steps 3 and 4 as needed
  6. Submit a pull request back to the upstream repository

Merge Model

This repository uses squash merges to group all related commits in a given pull request into a single commit upon acceptance and merge into the main branch. This has several benefits:

  1. Keeps the commit history on the main branch focused on high-level narrative
  2. Enables people to make lots of small commits without worrying about muddying up the commit history
  3. Commits correspond 1-to-1 with pull requests

Code Style

This project uses black to automatically enforce a consistent code style. You can apply black and other pre-configured linters with tox -e lint.

Each of these checks are run on each commit using GitHub Actions as a continuous integration service. Passing all of them is required for accepting a contribution. If you're unsure how to address the feedback from one of these tools, please say so either in the description of your pull request or in a comment, and we will help you.

Logging

Python's builtin print() should not be used (except when writing to files). If you're in a command line setting or main() function for a module, you can use click.echo(). Otherwise, you can use the builtin logging module by adding logger = logging.getLogger(__name__) below the imports at the top of your file.

Testing

Functions in this repository should be unit tested. These can be written using the unittest framework in the tests/ directory. You can check that the unit tests pass with tox -e py. These tests are required to pass for accepting a contribution.

Syncing your fork

If other code is updated before your contribution gets merged, you might need to resolve conflicts against the main branch. After cloning, you should add the upstream repository with

$ git remote add lubianat https://github.com/lubianat/wdcuration.git

Then, you can merge upstream code into your branch. You can also use the GitHub UI to do this by following this tutorial.

Python Version Compatibility

This project aims to support all versions of Python that have not passed their end-of-life dates. After end-of-life, the version will be removed from the Trove qualifiers in the setup.py and from the GitHub Actions testing configuration.

See https://endoflife.date/python for a timeline of Python release and end-of-life dates.

Acknowledgements

These code contribution guidelines are derived from the cthoyt/cookiecutter-snekpack Python package template. They're free to reuse and modify as long as they're properly acknowledged.