Contributing

We welcome contributions to the Spherinator project. This document outlines the guidelines for contributing to the project. Don’t worry about the length of this document. There are various ways to contribute to the project at different levels. Just get started, and we will help you through the process. Finally, all the guidelines and checks are in place to ensure the quality of the project.

Code of Conduct

The project follows the Contributor Covenant Code of Conduct. Please read the code of conduct before contributing to the project.

Use best practices for a clean codebase

The Python code must adhere to the PEP8 Python coding style guide for formatting and syntax. The Google Python Style Guide provides additional guidelines for writing clean and readable code. The Spherinator is using the design principles of the PyTorch Lightning library.

Python dependencies

The project uses uv for dependency management. The dependencies are listed in the pyproject.toml file. To add new dependencies, use the command uv add. It is recommended to keep the number of dependencies to a minimum.

Documentation

Write docstrings for all public modules, functions, classes, and methods. Follow docstring conventions as outlined by PEP 257. The user documentation is located in the docs directory and will be generated with Sphinx and hosted on Read The Docs.

Testing

The code is tested using pytest. All tests are located in the tests directory. Please write tests for all new code and ensure all tests pass before creating a pull request. The CI workflow will run the tests and fail if any test fails.

Continuous Integration

GitHub Actions is used for continuous integration. The CI workflow is defined in .github/workflows/python-package.yml. The CI workflow runs the tests and checks the code style and the code formatting on every push to the repository.

Code Formatting

The Python code must be formatted with black. This can be done manually by running black . in the project directory or by installing the vscode extension ms-python.black-formatter. The format on save option is enabled for vscode in the .vscode/settings.json file. The CI workflow will check the code formatting and fail if the code is not formatted correctly.

Static code analysis

The code will be analyzed using flake8. The linting rules are defined in the .flake8 file. The linter can be run manually by running flake8 in the project directory. The CI workflow will check the code for any issues reported by flake8 and fail if any issues are found.

Pull requests

The project uses the GitHub flow to manage pull requests.

Create a fork of the repository. Although you can create a branch in the main repository, creating a fork for better isolation is recommended.
Create a branch in your fork. Let the branch name describe the changes you are making.
Make the changes in the branch.
Check if all the checks are passing. If not, fix the issues and push the changes to the branch.
Create a pull request from your branch to the main repository and describe your changes.
The pull request will be reviewed by the maintainers. The review process may involve multiple iterations of changes and reviews.
Please keep the branch up to date with the main repository by rebasing it on the main branch if necessary.
Once the pull request is approved, it will be merged into the main repository, and the feature branch will be deleted.

Issues

If you find a bug or have a feature request, please create an issue in the GitHub issue tracker.

Thank you for contributing to the Spherinator project!