CONTRIBUTING.md

# Contributing to xiaohongshu-Loop Thanks for your interest in contributing! 🎉 This document covers how to file issues, propose features, and submit pull requests. ## Code of Conduct This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By participating you agree to abide by it. ## I have a question - **General how-to / usage**: open a [Discussion](https://github.com/zhenyu666-debug/xiaohongshu-Loop/discussions) - **Bug / feature**: open an [Issue](https://github.com/zhenyu666-debug/xiaohongshu-Loop/issues/new/choose) - **Security issue**: see [SECURITY.md](SECURITY.md) (do **not** file a public issue) ## Filing an issue We use issue templates - please pick the right one: - **Bug report** - something is broken - **Feature request** - you want a new capability Fill in the template as much as you can. For bugs, please include: - OS / Python version / Node version - `xiaohongshu-saas/app/__init__.py` version string (or commit hash) - Minimal reproduction (code snippet, command, screenshot) - Expected vs actual behavior - Relevant logs (with secrets redacted!) ## Development setup ### 1. Fork & clone ```bash git clone https://github.com/<you>/xiaohongshu-Loop.git cd xiaohongshu-Loop git remote add upstream https://github.com/zhenyu666-debug/xiaohongshu-Loop.git ``` ### 2. Create a branch ```bash git checkout -b feat/<short-name> # feature git checkout -b fix/<short-name> # bug fix git checkout -b docs/<short-name> # docs only git checkout -b refactor/<short-name> ``` Branch names use **kebab-case**. ### 3. Set up env ```bash # Backend cd xiaohongshu-saas python -m venv .venv && source .venv/bin/activate pip install -e ".[dev]" playwright install chromium # Frontend cd ../web/console npm install ``` ### 4. Make changes Code style: - Python: `ruff check .` (enforced by CI) - Python formatter: `ruff format .` - TypeScript: `npm run lint` and `npm run type-check` - No wildcard imports, no `console.log` left in committed code Commit messages: - Imperative mood: "Add SSE backpressure", not "Added" / "Adds" - First line <= 72 chars - Body explains **why**, not **what** (the diff shows what) - Reference issues: `Closes #123` / `Refs #45` Example: ``` fix(console): clamp candidate list render to 200 rows Virtualization wasn't kicking in because we passed the raw `rows` array instead of the memoized `displayRows`. Above ~200 rows the React tree re-renders every keystroke. Closes #98 ``` ### 5. Tests - **All PRs must include tests** for changed behavior - Run locally: `pytest -q tests` (backend) / `npm test` (frontend) - New tests should be deterministic - mock `datetime.now()`, random, network - Bug fixes should include a regression test that fails without the fix ### 6. Push & open a PR ```bash git push origin feat/<short-name> gh pr create --title "Short title" --body "..." ``` Use the [PR template](.github/PULL_REQUEST_TEMPLATE.md). The CI will run automatically. ## PR review process 1. **CI must pass** (lint + test) 2. At least **one maintainer approval** 3. No merge conflicts 4. If your PR changes public API or CLI behavior, update the docs in the same PR Auto-fix will not touch your PR - it only runs on `main` after merge. ## Release process 1. Maintainer merges PR with `feat:` / `fix:` conventional commit 2. Maintainer runs `./scripts/release.sh <version>` (bumps version, updates CHANGELOG) 3. Tag pushed, GitHub Actions publishes a Release with the `.exe` artifact ## What we accept ✔️ Encouraged: - Bug fixes with regression tests - Documentation improvements (typos, clarity, examples) - Performance improvements (with benchmarks) - New channel adapters (douyin / kuaishou / etc.) - Observability (more metrics, traces, dashboards) ❌ Probably not: - New dependencies without a strong reason - Breaking API changes without migration plan - Platform-specific hacks that don't generalize ## Security Never commit: - Real cookies / tokens / session IDs - Production database dumps - API keys If you find a security issue, follow [SECURITY.md](SECURITY.md). Please do **not** open a public issue. ## Communication - **GitHub Issues**: bugs, features - **GitHub Discussions**: how-tos, ideas, show-and-tell - **PR comments**: code review only ## License By contributing you agree your code is licensed under the project's [MIT License](LICENSE).