Contributing

Contributors

Opening issues and bug reports

When opening a new issue or submitting a bug report, please include:

  1. A clear, descriptive title
  2. For bug reports:
    • Description of the expected behavior
    • Description of the actual behavior
    • Steps to reproduce the issue
    • Version information (OS, Python version, package version)
    • Any relevant error messages or screenshots
  3. For feature requests:
    • Description of the proposed feature
    • Use case or motivation for the feature
    • Any implementation suggestions (optional)

Labels help categorize issues: - Use bug for reporting problems - Use enhancement for feature requests - Use documentation for documentation improvements - Use question for general queries

Contributing code

To contribute code to the project:

  1. Fork the repository and clone your fork locally
  2. Create a new branch from main with a descriptive name
  3. Review the customization, architecture, and authentication pages for guidance on design patterns and code structure and style
  4. Ensure all tests pass, including mypy type checking
  5. Stage, commit, and push your changes to the branch:
    • Use clear, descriptive commit messages
    • Keep commits focused and atomic
  6. Submit your pull request:
    • Provide a clear description of the changes
    • Link to any related issues

Rendering the documentation

The README and documentation website are rendered with Quarto. If you make changes to the .qmd files in the root folder and the docs folder, you will need to re-render the docs with Quarto.

Quarto expects environment variables to be set in a file called _environment, so before running Quarto render commands, you should copy your .env file to _environment.

# To copy the .env file to _environment
cp .env _environment
# To render the documentation website
uv run quarto render
# To render the README
uv run quarto render index.qmd --output-dir . --output README.md --to gfm

Due to a quirk of Quarto, an unnecessary index.html file is created in the root folder when the README is rendered. This file can be safely deleted.

Note that even if your pull request is merged, your changes will not be reflected on the live website until a maintainer republishes the docs.

Maintainers

Git flow

When creating new features,

  1. Open a Github issue with the label feature and assign it to yourself.
  2. Create a new branch from the issue sidebar.
  3. Follow the instructions in the popup to check out the branch locally and make your changes on the branch.
  4. Commit your changes and push to the branch.
  5. When you are ready to merge, open a pull request from the branch to main.
  6. Assign someone else for code review.

Publishing the documentation

To publish the documentation to GitHub Pages, run the following command:

uv run quarto publish gh-pages