Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
171 lines (122 loc) · 6.18 KB

CONTRIBUTING.md

File metadata and controls

171 lines (122 loc) · 6.18 KB
Raw

Contributing to tsbootstrap

Contributions are welcome: bug fixes, new features, and documentation improvements.

Table of Contents

  1. Code of Conduct
  2. Getting Started
  3. Issue Creation Guidelines
  4. Making Contributions
  5. Improving Documentation
  6. Style Guides
  7. Community and Communication
  8. Joining The Project Team

Code of Conduct

Contributors must follow the Code of Conduct.

Getting Started

Environment Setup

tsbootstrap uses uv for development. Requires Python 3.10 or higher.

  1. Fork and clone the repository, then change into the project root.

  2. Sync the locked development environment:

uv sync --extra dev

uv sync builds the locked virtual environment with an editable install, so your edits take effect immediately. Invoke tools with uv run, e.g. uv run pytest.

  1. Install the hooks:
uv run pre-commit install
scripts/install-hooks.sh

pre-commit install runs Ruff (lint and format) on each commit. scripts/install-hooks.sh points the clone at .githooks/, enabling the version-controlled pre-push gate that runs Ruff, mypy, and pyright with the same --extra dev --extra mcp extras CI uses, so a type error involving an optional dependency is caught locally instead of on the pull request. Skip the pre-push gate in an emergency with PRE_PUSH_SKIP=1 git push.

To reproduce the SonarCloud scan locally before pushing, set SONAR_TOKEN and run scripts/sonar-local.sh (optionally passing a coverage XML path).

  1. Verify the installation:
uv run python -c "import tsbootstrap; print(tsbootstrap.__version__)"

This prints the installed version.

  1. Run the test suite:
uv run pytest tests/

That is a single-process run. For the whole suite, ask for the pytest-xdist parallelism that CI uses, which is several times faster:

uv run pytest tests/ -n auto --dist loadscope --max-worker-restart 3

The flags are not in addopts, because addopts reaches every pytest run in the repository and several of those must stay single-process. DEVELOPER_NOTES.md explains why.

Dependency Policy (cooldown and pinned uv)

The project enforces a 7-day dependency cooldown: exclude-newer = "7 days" in [tool.uv] makes every uv lock refuse distributions published within the last week, so a compromised release must survive a week of public scrutiny before it can enter the lockfile. Two practical consequences:

  • uv lock --upgrade will select the newest release that is at least 7 days old, not the absolute newest. This is intentional.
  • To adopt an urgent security fix younger than the window, do not lift the cooldown. Add a scoped override and remove it once the release ages past the window: 
    [tool.uv]
exclude-newer-package = { somepackage = "2026-07-10T00:00:00Z" }

The uv version itself is pinned via required-version in [tool.uv], written as a floor (>=X.Y.Z). Every setup-uv step in CI sets resolution-strategy: lowest, so CI installs exactly the floor instead of the latest release, while Dependabot, which runs the uv it bundles, can still update uv.lock. If your local uv is older than the floor, upgrade (uv self update, or your package manager's equivalent). Bumps to the floor belong in their own commit with a green uv lock --check, and never above the uv Dependabot bundles.

Finding Your First Issue

New contributors can pick up an issue labeled good first issue or help wanted.

Issue Creation Guidelines

Reporting Bugs

When reporting a new bug, first check it is not already reported, then open an issue with:

  • A clear title and description.
  • Steps to reproduce.
  • Expected behavior.
  • Actual behavior.
  • Screenshots or code snippets, if applicable.

Suggesting Enhancements

When suggesting an enhancement, include:

  • A clear title and detailed description.
  • Why this enhancement would be beneficial.
  • Any potential implementation details or challenges.

Asking Questions

Ask in GitHub Discussions or open an issue, with as much context as you can give.

Making Contributions

Your First Code Contribution

The Contributor's Guide has step-by-step instructions for a first contribution.

Pull Request Process

  1. Fork the repository and create your branch from main.
  2. If you've added code, add tests.
  3. Ensure the test suite passes.
  4. Update the documentation if necessary.
  5. Submit a pull request.

Improving Documentation

To update the documentation:

Style Guides

Code Style

Ruff handles linting and formatting, via pre-commit hooks and in CI.

Commit Messages

Follow Conventional Commits for clear, structured commit messages.

Documentation Style

Write documentation in plain English. Use markdown for formatting.

Community and Communication

Use GitHub Discussions for questions and GitHub Issues for bugs and features.

Joining The Project Team

To join the core team, email sankalp.gilda@gmail.com with your contributions.