Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
141 lines (101 loc) · 5.23 KB

CONTRIBUTING.md

File metadata and controls

141 lines (101 loc) · 5.23 KB

Contributing

We're so excited you're interested in helping with SuperTokens! We are happy to help you get started, even if you don't have any previous open-source experience 😊

New to Open Source?

  1. Take a look at How to Contribute to an Open Source Project on GitHub
  2. Go through the SuperTokens Code of Conduct

Where to ask Questions?

  1. Check our Github Issues to see if someone has already answered your question.
  2. Join our community on Discord and feel free to ask us your questions

Development Setup

Prerequisites

  • Python 3.8 or above
  • Docker (required to run tests)
  • IDE: PyCharm (recommended) or VS Code
  • changie (required to add changelog entries) 
    brew install changie   # macOS
# or download a binary from https://github.com/miniscruff/changie/releases

Project Setup

  1. Fork and clone supertokens-python.
  2. Create and activate a virtual environment: 
    python3 -m venv venv && source venv/bin/activate
  3. Install project dependencies: 
    make dev-install
  4. Install framework-specific extras if needed: 
    make with-fastapi   # or with-flask, with-django, with-drf
  5. Set up git hooks (enforces version sync between setup.py and constants.py): 
    make set-up-hooks

Modifying Code

  • Open the project in your IDE and start modifying.
  • Run make lint to check for lint/type errors before committing (the pre-commit hook also runs this).

Testing

Caution

Tests create multiple applications on the SuperTokens core and must not be run against production instances. Use the Docker compose.yml provided.

  1. Run all tests (starts required containers automatically):

    make test

    Set SUPERTOKENS_CORE_VERSION to test against a specific core version (defaults to latest).

  2. Run a specific test file or function:

    docker compose up --wait
pytest ./tests/path/to/test_file.py
pytest ./tests/path/to/test_file.py::test_function_name

    You can also use your IDE's built-in test runner: VS Code Python Testing | PyCharm Testing

Changelog

Every pull request must include a changelog fragment describing the change. We use changie to manage changelog entries.

Adding a fragment

Run the following command from the repo root and follow the prompts:

changie new

This creates a small YAML file under .changes/unreleased/. Commit this file with your changes — CI will check that it exists.

Kinds to choose from:

Kind When to use
Added New feature or capability
Changed Change to existing behaviour
Fixed Bug fix
Breaking Changes Anything that breaks backwards compatibility
Infrastructure CI, tooling, dependency changes
Deprecated Something that will be removed in a future version
Removed Removal of a feature
Security Security fix

Skipping the changelog check

If a PR has no user-facing impact (e.g., a documentation typo fix or test refactor), add the Skip-Changelog label on GitHub to bypass the check.

Pull Request

  1. Make sure all tests pass before submitting.
  2. Reference the relevant issue and give a clear description of the changes.
  3. Ensure the PR title follows the Conventional Commits specification (enforced by CI).
  4. Include a changelog fragment (see Changelog above) or add the Skip-Changelog label.

Implementing RecipeInterfaces

  • Make sure all CRUD operations are available via the (a)?syncio modules of that recipe.
  • Make sure the corresponding RecipeImplementation takes type imports from the interfaces.py file of that recipe. This allows users to copy/paste that code into their project with standard imports.

Implementing APIInterfaces

  • Make sure the corresponding APIImplementation takes type imports from the interfaces.py file of that recipe. This allows users to copy/paste that code into their project with standard imports.

Generating Docs

make build-docs

This generates API docs in a html/ folder.

SuperTokens Community

SuperTokens is made possible by a passionate team and a strong community of developers. If you have any questions or would like to get more involved:

Additional resources: