Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
220 lines (149 loc) · 6.07 KB

CONTRIBUTING.md

File metadata and controls

220 lines (149 loc) · 6.07 KB

Contributing to DeepTutor

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.

Discord  WeChat  Feishu

Table of Contents

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

  1. Fork & Clone the repository.
  2. Sync with the target branch before starting:
git checkout dev && git pull origin dev
  1. Create your feature branch from the target branch:
git checkout -b feature/your-feature-name
  1. Develop your changes, following the coding standards below.
  2. Validate by running pre-commit checks:
pre-commit run --all-files
  1. 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!