Contribution Guide#

Setting up the environment#

  1. If you do not have already have Astral’s UV installed, run make install-uv

  2. Run uv sync --all-groups to create a virtual environment and install the dependencies

  3. If you’re working on the documentation and need to build it locally, install the extra dependencies with `` uv sync –group docs``

  4. Install pre-commit

  5. Run pre-commit install to install pre-commit hooks

Code contributions#

Workflow#

  1. Fork the fullstack repository

  2. Clone your fork locally with git

  3. Set up the environment

  4. Make your changes

  5. (Optional) Run pre-commit run --all-files to run linters and formatters. This step is optional and will be executed automatically by git before you make a commit, but you may want to run it manually in order to apply fixes

  6. Commit your changes to git

  7. Push the changes to your fork

  8. Open a pull request. Give the pull request a descriptive title indicating what it changes. If it has a corresponding open issue. For example a pull request that fixes issue bug: Increased stack size making it impossible to find needle could be titled fix: Make needles easier to find by applying fire to haystack

Tip

Pull requests and commits all need to follow the Conventional Commit format

Project documentation#

The documentation is located in the /docs directory and is built with ReST and Sphinx. If you’re unfamiliar with any of those, ReStructuredText primer and Sphinx quickstart are recommended reads.

Docs theme and appearance#

We welcome contributions that enhance / improve the appearance and usability of the docs. We use a custom theme that inherits the PyData Sphinx Theme, which comes with a lot of options out of the box. If you wish to contribute to the docs style / setup, or static site generation, you should consult the theme docs as a first step.

Running the docs locally#

To run or build the docs locally, you need to first install the required dependencies:

uv sync --group docs

Then you can serve the documentation with make docs-serve, or build them with make docs

Writing and editing docs#

We welcome contributions that enhance / improve the content of the docs. Feel free to add examples, clarify text, restructure the docs etc., but make sure to follow these guidelines:

  • Write text in idiomatic english, using simple language

  • Keep examples simple and self contained

  • Provide links where applicable

  • Use intersphinx wherever possible when referencing external libraries

  • Provide diagrams using mermaidjs where applicable and possible

Creating a new release#

  1. Increment the version in pyproject.toml

    Note

    The version should follow semantic versioning and PEP 440.

  2. Commit and push.

  3. In GitHub go to the releases tab

  4. Pick “Draft a new release”

  5. Give it a title and a tag, both vX.X.X

  6. Fill in the release description. You can let GitHub do it for you and then edit as needed.

  7. Publish the release.

  8. Go to Actions and approve the workflow

  9. Check that the workflow runs successfully