Contributing

Contributions are welcome, and they are greatly appreciated! The development of this package takes place on GitHub. Issues, bugs, and feature requests should be reported there. Code and documentation can be improved by submitting a pull request. Please add documentation and tests for any new code.

How to Contribute

To contribute, follow these steps:

  1. Fork the repository: Start by forking the repository to your own GitHub account.

  2. Clone the repository: Clone your forked repository to your local machine.

$ git clone https://github.com/your-username/pytspl.git

  1. Install the dependencies: Install the dependencies using Poetry.

$ poetry install

  1. Create a new branch: Create a new branch for your changes.

$ git checkout -b your-branch-name

5. Make your changes: Improve or add functionality in the pytspl folder, along with corresponding unit tests in pytspl/tests/test_*.py (with reasonable coverage). If you have a nice example to demonstrate the use of the introduced functionality, please consider adding a tutorial in doc/tutorial.

  1. Update documentation: Update README.md and CHANGELOG.rst if applicable.

7. Check the style and run tests: Ensure your code meets the style guidelines and all tests pass. You can do this by running the following commands:

$ poetry run pflake8 pytspl
$ poetry run pytest

  1. Build the documentation: First, clean the existing build files:

$ make -C doc clean

Then, build the documentation to ensure it builds correctly. The documentation will be automatically published to the Read the Docs once the pull request is merged to the main branch.

$ poetry run sphinx-build -b html -d doc/_build/doctrees doc doc/_build/html

1. Check coverage: Check the generated coverage report at htmlcov/index.html to make sure the tests reasonably cover the changes you’ve introduced. The coverage report can be generated by running:

$ poetry run coverage run -m pytest && poetry run coverage report -m

10. Bump the version: If you have made changes that affect the functionality of the package, you should bump the version number in the pyproject.toml file. The version number should follow the Semantic Versioning guidelines. Additionally, bump the version in the pytspl/__init__.py file.

11. Submit a pull request: Go to the original repository on GitHub and submit a pull request. Ensure you fill in the pull request template with all relevant details.

Making a release

Once your pull request has been merged, create a release using the format pytspl-vX.Y.Z. This will trigger a GitHub Action that will build the package and publish it to PyPI. Additionally, the documentation will be built and published to Read the Docs. The workflow is defined in the .github/workflows/release.yml file.

Thank you for contributing!