Contributing to LSAPy

No matter the scope of your contribution, help is always welcome!

The issue tracker is the best place to start if you want to contribute to LSAPy. You can get involved in different ways:

• Submitting feedbacks: We welcome any feedback on the library, whether it’s about the API, the documentation, or anything else.

• Suggesting new features: If you have an idea for a new feature or improvement. Explain your idea in details and provide any thoughts you have on how it could be implemented.

• Reporting bugs: If you find a bug, please report it making sure to include as much information as possible to help us reproduce the bug (e.g., operating system, local setup details, steps to reproduce it…).

The issue tracker is also the place to ask questions about the library. The maintainers and the community will be happy to help you.

Contribution Workflow

Below is the steps to follow for contributing to the project.

1. Fork the LSAPy repository on GitHub to your own account.

2. Clone your forked repository to your local machine.

   git clone git@github.com:<your_username>/lsapy.git
   cd lsapy/
   

3. Create a virtual environment (conda is recommended) and install the dependencies.

   conda env create -f environment.yml
   conda activate lsapy
   python -m pip install -e .
   

4. Create a new branch for your changes.

   git checkout -b name-of-your-bugfix-or-feature
   

   You can now make changes.

5. Before committing your changes, we ask that you install pre-commit in your development environment and run git hooks to ensure that your code adheres to the project’s coding standards:

   # To install the necessary pre-commit hooks:
   pre-commit install
   # To run pre-commit hooks manually:
   pre-commit run --all-files
   

   Instead of pre-commit, you can check individual hooks manually with ruff:

   ruff check --fix --show-fixes src/lsapy/
   ruff format src/lsapy/
   

   This will automatically format your code and fix any linting issues.

6. The last step before committing is to run the tests:

   pytest --doctest-modules src/lsapy/ # to run doctests
   

7. Commit your changes and push your branch.

   git add *
   git commit -m "Short description of your changes"
   git push origin name-of-your-bugfix-or-feature
   

8. Create a pull request on GitHub.

   Before creating a pull request, we first ask you to open an issue in the GitHub repository. Describe the bug you would like to fix or the feature you would like to add. Link the issue to your pull request.

Note

Longer Term Commitment ?

While the project is still in its early stages, a bigger maintainers team may be required in the future if the project grows. If you like the project and are interested in joining the maintainers team, please reach out to us. We will be happy to discuss it with you.

Reminder for maintainers

This section provides some useful information for maintainers.

Versioning

The project follows Semantic Versioning scheme:

major.minor.patch-releaseX
  |     |     |      |   |
  |     |     |      |   +--- Build number (e.g., 1, 2, 3...)
  |     |     |      +------- Degree of production (e.g., dev, alpha, beta)
  |     |     +-------------- Patch release (e.g., bug fixes)
  |     +-------------------- Minor release (e.g., new features)
  +-------------------------- Major release (e.g., breaking changes)

Packaging and Deployment

Note

This section comes largely from the xclim Contributing guidelines. Small edits have been made to match LSAPy project.

This section serves as a reminder for the maintainers on how to prepare the library for a tagged version and how to deploy packages to TestPyPI and PyPI.

When a new version has been minted (features have been successfully integrated test coverage and stability is adequate), maintainers should update the pip-installable package (wheel and source release) on PyPI.

From a new branch (e.g. prepare-v123), open a Pull Request and make sure all your changes to support a new version are committed (update the entry for newest version in CHANGELOG.rst), then run:

bump-my-version bump <option>  # possible options: major / minor / patch / release / build

These commands will increment the version and create a commit with an autogenerated message.

For PyPI releases/stable versions, ensure that the last version bumping command run is $ bump-my-version bump release to remove the -dev. These changes can now be merged to the prepare-v123 branch:

git push origin prepare-v123

With this performed, we can tag a version that will act as the GitHub-provided stable source archive. Be sure to only tag from the `main` branch when all changes from PRs have been merged! The commands needed are:

git tag v1.2.3
git push --tags

Note

All tags pushed to GitHub will trigger a build and publish a package to TestPyPI by default.

The Automated Approach

The simplest way to package LSAPy is to “publish” a version on GitHub. GitHub CI Actions are presently configured to build the library and publish the packages on PyPI automatically.

Warning

A published version on PyPI can never be overwritten. Be sure to verify that the package published at https://test.pypi.org/project/lsapy/ matches expectations before publishing a version on GitHub.

The Manual Approach

The manual approach to library packaging for general support (pip wheels) requires that the flit library is installed.

From the command line on your Linux distribution, simply run the following from the clone’s main dev branch:

# To build the packages (sources and wheel)
flit build

# To upload to PyPI
flit publish

The new version based off of the version checked out will now be available via pip ($ pip install lsapy).

Credits

This document is inspired by the xclim Contributing guidelines.