Contributing to DeepTutor

April 23, 2026 · View on GitHub

Thank you for your interest in contributing to DeepTutor! We welcome developers of all skill levels to help build the next-generation intelligent learning companion.

Maintainers
Branching Strategy
Quick Start for Contributors
Development Setup
Code Quality & Security
Coding Standards
Commit Message Format
Security Best Practices

Maintainer

@pancacake — Currently just me!

Branching Strategy

We use a multi-branch model to keep development organized:

Branch	Purpose	Stability
`dev`	General development	May have bugs or breaking changes
`multi-user`	Multi-user scenario development	Experimental, focused on multi-tenant features

Important

Please do not submit PRs directly to main. All contributions should target dev or multi-user.

Which Branch Should I Target?

Target dev if your PR includes:

New features or functionality
Refactoring that may affect existing behavior
Changes to APIs or configuration
General bug fixes

Target multi-user if your PR includes:

Multi-user / multi-tenant related features
Session isolation, user management, or permission changes
Collaborative or shared workspace functionality

Note

When in doubt, target dev — it is the default development branch.

Quick Start for Contributors

Fork & Clone the repository.
Sync with the target branch before starting:

git checkout dev && git pull origin dev

Create your feature branch from the target branch:

git checkout -b feature/your-feature-name

Develop your changes, following the coding standards below.
Validate by running pre-commit checks:

pre-commit run --all-files

Submit your Pull Request to the correct target branch (not main unless it's a hotfix or docs-only change).

Tip

Browse our Issues for tasks labeled good first issue to find a great starting point. Comment on the issue to let others know you're working on it.

Development Setup

Setting Up Your Environment

Step 1: Create a virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 2: Install dependencies

pip install -e ".[all]"

Setting Up Pre-commit (First Time Only)

Step 1: Install pre-commit

pip install pre-commit
# Or: conda install -c conda-forge pre-commit

Step 2: Install Git hooks

pre-commit install

Step 3: Initialize the Secrets Baseline

If you encounter false-positive secrets (like API hash placeholders), update the baseline:

detect-secrets scan > .secrets.baseline

Common Commands

Task	Command
Check all files	`pre-commit run --all-files`
Check quietly	`pre-commit run --all-files -q`
Update tools	`pre-commit autoupdate`
Emergency skip	`git commit --no-verify -m "message"` (not recommended)

Code Quality & Security

We use automated tools (configured via pyproject.toml and .pre-commit-config.yaml) to maintain high standards:

Tool	Purpose
Ruff	Python linting and formatting
Prettier	Frontend & config file formatting
detect-secrets	Hardcoded secret scanning
pip-audit	Dependency vulnerability scanning
Bandit	Security issue analysis
MyPy	Static type checking
Interrogate	Docstring coverage reporting

Important

Local pre-commit hooks may only show warnings, but CI will perform strict checks and automatically reject PRs that fail.

Coding Standards

Python

Use type hints for all function signatures.
Prefer f-strings for string formatting.
Follow PEP 8 (enforced by Ruff).
Keep functions small and focused on a single responsibility.

Documentation

Every new module, class, and public function should have a docstring (Google Python Style Guide format).
Update README.md if your change introduces new features or configuration.

Commit Message Format

<type>: <short description>

[optional body]

Type	Description
`feat`	A new feature (MINOR version bump)
`fix`	A bug fix (PATCH version bump)
`docs`	Documentation only changes
`style`	Formatting, no logic changes
`refactor`	Code restructuring, no new features or fixes
`test`	Adding or correcting tests
`chore`	Build process, tooling, or dependency updates

Security Best Practices

File Uploads

Size Limits: General files capped at 100 MB; PDFs capped at 50 MB.
Validation: Multi-layer validation (extension + MIME type + content sanitization).
Sanitization: All filenames are sanitized to prevent path traversal.

Development Standards

Subprocesses: Always use shell=False to prevent command injection.
Pathing: Use pathlib.Path for cross-platform compatibility.
Line Endings: LF (Unix) line endings enforced for critical scripts via .gitattributes.

Questions? Reach out on Discord. Let's build the future of AI tutoring together!