Thank you for your interest in contributing to S2FFT 🎉! We welcome contributions of all forms, including writing tutorials, improving documentation, creating bug reports or feature requests and updates to the package's code and infrastructure.
If you don't feel like you currently have time to contribute but would like to show your support, starring the repository or posting about it on social media is always appreciated!
We use the All Contributors bot to record all forms of contribution to the project; you can see the list of all the wonderful people who have contributed to the project so far in the README. If you make a contribution to the project one of the maintainers should record your contribution by adding a message tagging the bot in the relevant issue or pull request thread. If we forget to do this please remind us!
If you have a question please first check if it is covered in the documentation or if there is an existing issue which answers your query.
If there is not a relevant existing issue, to report a problem you are having with the package or request a new feature please raise an issue.
When reporting a bug; please describe the expected behaviour, what you actually observe, and provide sufficient information for someone else to reproduce the problem. Ideally this should be in the form of a minimal reproducible example which reproduces the error while as being as small and simple as possible.
We use a fork and pull-request model for external contributions. Before opening a pull request that proposes substantial changes to the repository, for example adding a new feature or changing the public interface of the package, please first raise an issue outlining the problem the proposed changes would address to allow for some discussion about the problem and proposed solution before significant time is invested.
If you have not made an open-source contribution via a pull request before you may find this detailed guide by asmeurer helpful. A summary of the main steps is as follows:
- Fork the repository and create a local clone of the fork.
- Create a new branch with a descriptive name in your fork clone.
- Make the proposed changes on the branch, giving each commit a descriptive commit message.
- Push the changes on the local branch to your fork on GitHub.
- Create a pull request, specifying the fork branch as the source of the changes, giving the pull request a descriptive title and explaining what you are changing and why in the description. If the pull-request is resolving a specific issue, use keywords to link the appropriate issue.
- Make sure all automated status checks pass on the pull request.
- Await a review on the changes by one of the project maintainers, and address any review comments.
- Once all status checks pass and the changes have been approved by a maintainer the pull request can be (squash) merged.
We aim to broadly follow Scientific Python's SPEC0 recommendation - that is we will support Python versions for three years after their initial release and core scientific Python packages such as NumPy for two years after their initial release.
The Python code in S2FFT uses the Black code style and we use Ruff to lint and autoformat the code.
C++ code in S2FFT follows the Google C++ code style and we use ClangFormat to autoformat the code.
We use pre-commit hooks to automatically check changes respect formatting and linting rules. You can install these hooks in your local repository by installing pre-commit and running
pre-commit installfrom the root of the repository.
The installed pre-commit hooks will run a series of checks on any staged changes when initiating a commit. If there are problems with the changes this will be flagged in the terminal output. Where possible some problems may be automatically fixed - in this case the updated changes will need to be staged and committed again.