docs: sync contributing and README

[FutureUnreal]

No description provided.

[qodo-code-review]

Review Summary by Qodo

Update documentation with version requirements and repository details

📝 Documentation

Walkthroughs

Description

• Update Python version requirement from 3.8+ to 3.10+ across docs
• Correct repository URL from WhaleWhisper to whale-whisper
• Update frontend port from 5173 to 5174 and add pnpm version specification
• Clarify code organization structure and add security vulnerability reporting guidelines
• Update backend command to use uv run and remove frontend typecheck step

Diagram

flowchart LR
  A["Documentation Files"] -->|Update Python 3.8+ to 3.10+| B["Version Requirements"]
  A -->|Correct URLs| C["Repository References"]
  A -->|Update ports & tools| D["Setup Instructions"]
  A -->|Clarify structure| E["Project Organization"]
  A -->|Add guidelines| F["Security & Contributing"]

Loading

File Changes

1. CONTRIBUTING.md 📝 Documentation +29/-23

Sync version requirements and clarify setup instructions

• Updated Python version requirement from 3.8+ to 3.10+ with reference to backend/pyproject.toml
• Corrected repository clone URL from WhaleWhisper to whale-whisper
• Updated frontend development port from 5173 to 5174
• Changed backend command to use uv run uvicorn instead of direct uvicorn
• Clarified frontend code organization: shared code in frontend/packages/* vs app-specific in
 frontend/apps/*/src
• Removed pnpm run typecheck from frontend build test section
• Added security vulnerability reporting guidelines referencing .github/SECURITY.md
• Updated PR submission checklist wording from "Fill Out PR Template" to "Write a Clear PR
 Description"
• Added environment version recommendations: Node.js 20, pnpm 9.12.2

CONTRIBUTING.md

---

2. README.md 📝 Documentation +16/-14

Update version requirements and project structure documentation

• Updated Python badge from 3.8+ to 3.10+ in header
• Updated prerequisites: Python 3.10+ (CI: 3.11), Node.js 20+, pnpm 9.12.2
• Corrected frontend development port from 5173 to 5174
• Restructured project directory tree to reflect new frontend organization with apps/ subdirectory
• Updated contributor badge repository from base-nlp to whale-whisper
• Corrected all GitHub URLs from WhaleWhisper to whale-whisper
• Updated test command examples with specific paths and flags

README.md

---

[greptile-apps]

Greptile Overview

Greptile Summary

This PR synchronizes documentation with the current project state by correcting several inconsistencies between the docs and actual codebase configuration.

Key Updates:

• Fixed repository URL from datawhalechina/WhaleWhisper (PascalCase) to datawhalechina/whale-whisper (kebab-case) across all references
• Updated Python version requirement from 3.8+ to 3.10+ to match backend/pyproject.toml (requires-python = ">=3.10")
• Corrected frontend dev server port from 5173 to 5174 (verified in frontend/apps/web/vite.config.ts)
• Updated backend startup command from uvicorn to uv run uvicorn to align with recommended tooling
• Removed obsolete pnpm run typecheck command from frontend testing section (command doesn't exist in package.json)
• Enhanced project structure documentation in README.md to accurately reflect the frontend/apps/ and backend/ organization
• Added security vulnerability reporting section with reference to .github/SECURITY.md (file exists)
• Updated test commands with specific directory paths for clarity

All changes are validated against the actual codebase and improve documentation accuracy for contributors.

Confidence Score: 5/5

• This PR is safe to merge with no risks - purely documentation updates that improve accuracy
• Score of 5 given because this PR contains only documentation changes that have been verified against the actual codebase. All updates (repository URL, Python version, port numbers, commands, file structure) are factually correct and align with existing code. No code logic, dependencies, or functionality are modified. The changes improve contributor experience by ensuring documentation matches reality.
• No files require special attention

Important Files Changed

Filename	Overview
CONTRIBUTING.md	Updated documentation to reflect current project state: corrected repository URL from PascalCase to kebab-case, updated Python requirement to 3.10+, changed frontend port from 5173 to 5174, updated commands to use uv run, removed obsolete typecheck command, updated project structure references, and added security vulnerability reporting section
README.md	Synchronized README with current project configuration: updated Python badge from 3.8+ to 3.10+, corrected repository URLs, updated frontend port to 5174, improved project structure documentation to accurately reflect frontend/apps and backend organization, corrected contributor badge repository reference, and updated test commands with specific paths

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Repo as Repository
    participant CI as CI Environment
    participant Docs as Documentation

    Dev->>Repo: Identify documentation inconsistencies
    Note over Dev,Docs: Repository URL uses kebab-case<br/>Python version is 3.10+<br/>Frontend port changed to 5174<br/>Using uv for backend commands
    
    Dev->>Docs: Update CONTRIBUTING.md
    Note over Docs: - Fix repo URL (WhaleWhisper → whale-whisper)<br/>- Update Python 3.8+ → 3.10+<br/>- Update port 5173 → 5174<br/>- Change uvicorn → uv run uvicorn<br/>- Remove typecheck command<br/>- Add security reporting section
    
    Dev->>Docs: Update README.md
    Note over Docs: - Update Python badge to 3.10+<br/>- Fix repository URLs<br/>- Update frontend port<br/>- Improve project structure<br/>- Update test commands
    
    Dev->>Repo: Submit PR to dev branch
    Repo->>CI: Trigger documentation checks
    CI->>Repo: Verify consistency
    Note over CI,Repo: Python >=3.10 (pyproject.toml)<br/>Port 5174 (vite.config.ts)<br/>SECURITY.md exists

Loading

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. uv run blocks venv setup 🐞 Bug ✓ Correctness

Description

• CONTRIBUTING offers a “traditional venv” path that does not install/require uv, but the
  subsequent “Launch Dev Servers” command uses uv run ..., which will fail for contributors who
  chose the non-uv path and don’t have uv installed.
• This is a regression from the previous generic uvicorn ... command and can cause immediate
  onboarding friction (“command not found”) or confusion about which workflow is supported.
• The repo’s backend README explicitly documents that the pip/venv flow should use plain `uvicorn
  ..., so CONTRIBUTING should mirror that split (or clearly require uv` for all flows).

Code

CONTRIBUTING.md[97]

+uv run uvicorn app.main:app --reload --port 8090

Evidence

CONTRIBUTING.md documents two setup options (uv vs traditional venv), but then uses uv run
unconditionally for launching. The backend’s own README differentiates launch commands: uv run ...
only for the uv flow, and plain uvicorn ... for the pip/venv flow—showing CONTRIBUTING is
currently inconsistent with the documented supported workflows.

CONTRIBUTING.md[59-101]
backend/README.md[65-78]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`CONTRIBUTING.md` documents two backend setup flows (uv vs traditional venv), but the “Launch Dev Servers” section always uses `uv run ...`. This breaks the “traditional venv” path for contributors who don’t have `uv` installed (or expect to use `uvicorn` directly after activating `.venv`).

## Issue Context
The backend README already documents the correct split:
- uv flow: `uv run uvicorn ...`
- pip/venv flow: `uvicorn ...`

CONTRIBUTING should mirror that to avoid onboarding failures.

## Fix Focus Areas
- CONTRIBUTING.md[57-104]
- CONTRIBUTING.md[379-426]

## Suggested change
In both CN/EN sections, change the launch block to something like:
- If using uv:
 - `uv run uvicorn app.main:app --reload --port 8090`
- If using traditional venv:
 - (ensure `.venv` is activated)
 - `uvicorn app.main:app --reload --port 8090`

Optionally add a one-liner noting that `uv` must be installed to use the uv flow.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more

[github-actions]

PR #24 (docs-only) review:

• Size: S (82 lines changed, 2 files).
• Issues in modified lines (CONTRIBUTING.md, README.md): none.

gh can’t reach api.github.com from this runner, so I couldn’t apply the size/S label or submit the review. Run from an environment with GitHub API access:

REPO="datawhalechina/whale-whisper"
PR="24"

gh pr edit "$PR" --repo "$REPO" --add-label "size/S"

gh pr review "$PR" --repo "$REPO" --comment --body "$(cat <<'EOF'
## Codex PR Review

No significant issues identified in this PR.

### PR Size: S
- **Lines changed**: 82
- **Files changed**: 2

### Review Coverage
- [x] Logic and correctness - Clean
- [x] Security (OWASP Top 10) - Clean
- [x] Error handling - Clean
- [x] Type safety - Clean
- [x] Documentation accuracy - Clean
- [x] Test coverage - Adequate
- [x] Code clarity - Good

---
*Automated review by Codex AI*
EOF
)"