wehub-resource-sync
e4dcfc49aa
Tests / Import Check (Python 3.13) (push) Has been cancelled
Tests / Import Check (Python 3.14) (push) Has been cancelled
Tests / Python Tests (Python 3.11) (push) Has been cancelled
Tests / Python Tests (Python 3.12) (push) Has been cancelled
Tests / Python Tests (Python 3.14) (push) Has been cancelled
Tests / Test Summary (push) Has been cancelled
Tests / Lint and Format (push) Has been cancelled
Tests / Web Node Tests (push) Has been cancelled
Tests / Import Check (Python 3.11) (push) Has been cancelled
Tests / Import Check (Python 3.12) (push) Has been cancelled
Tests / Python Tests (Python 3.13) (push) Has been cancelled
221 lines
6.1 KiB
Markdown
221 lines
6.1 KiB
Markdown
# 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.
|
|
|
|
<p align="center">
|
|
<a href="https://discord.gg/eRsjPgMU4t"><img src="https://img.shields.io/badge/Discord-Join_Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
|
|
<a href="https://github.com/HKUDS/DeepTutor/issues/78"><img src="https://img.shields.io/badge/WeChat-Join_Group-07C160?style=for-the-badge&logo=wechat&logoColor=white" alt="WeChat"></a>
|
|
<a href="./Communication.md"><img src="https://img.shields.io/badge/Feishu-Join_Group-00D4AA?style=for-the-badge&logo=feishu&logoColor=white" alt="Feishu"></a>
|
|
</p>
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
- [Maintainers](#maintainers)
|
|
- [Branching Strategy](#branching-strategy)
|
|
- [Quick Start for Contributors](#quick-start-for-contributors)
|
|
- [Development Setup](#development-setup)
|
|
- [Code Quality & Security](#code-quality--security)
|
|
- [Coding Standards](#coding-standards)
|
|
- [Commit Message Format](#commit-message-format)
|
|
- [Security Best Practices](#security-best-practices)
|
|
|
|
---
|
|
|
|
## Maintainer
|
|
|
|
[@pancacake](https://github.com/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:
|
|
|
|
```bash
|
|
git checkout dev && git pull origin dev
|
|
```
|
|
|
|
3. **Create** your feature branch from the target branch:
|
|
|
|
```bash
|
|
git checkout -b feature/your-feature-name
|
|
```
|
|
|
|
4. **Develop** your changes, following the coding standards below.
|
|
5. **Validate** by running pre-commit checks:
|
|
|
|
```bash
|
|
pre-commit run --all-files
|
|
```
|
|
|
|
6. **Submit** your Pull Request to the correct target branch (not `main` unless it's a hotfix or docs-only change).
|
|
|
|
> [!TIP]
|
|
> Browse our [Issues](https://github.com/HKUDS/DeepTutor/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
|
|
|
|
<details>
|
|
<summary><b>Setting Up Your Environment</b></summary>
|
|
|
|
**Step 1: Create a virtual environment**
|
|
|
|
```bash
|
|
python -m venv venv
|
|
source venv/bin/activate # On Windows: venv\Scripts\activate
|
|
```
|
|
|
|
**Step 2: Install dependencies**
|
|
|
|
```bash
|
|
pip install -e ".[all]"
|
|
```
|
|
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>Setting Up Pre-commit (First Time Only)</b></summary>
|
|
|
|
**Step 1: Install pre-commit**
|
|
|
|
```bash
|
|
pip install pre-commit
|
|
# Or: conda install -c conda-forge pre-commit
|
|
```
|
|
|
|
**Step 2: Install Git hooks**
|
|
|
|
```bash
|
|
pre-commit install
|
|
```
|
|
|
|
**Step 3: Initialize the Secrets Baseline**
|
|
|
|
If you encounter false-positive secrets (like API hash placeholders), update the baseline:
|
|
|
|
```bash
|
|
detect-secrets scan > .secrets.baseline
|
|
```
|
|
|
|
</details>
|
|
|
|
### 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](https://discord.gg/eRsjPgMU4t). Let's build the future of AI tutoring together!
|