Initial commit
This commit is contained in:
Zhongwei Li
351
references/pr-checklist.md
Normal file
351
references/pr-checklist.md
Normal file
@@ -0,0 +1,351 @@
|
||||
# Pull Request Submission Checklist
|
||||
|
||||
A comprehensive checklist to ensure your PR is ready for review and meets open source contribution standards.
|
||||
|
||||
---
|
||||
|
||||
## Pre-Contribution Phase
|
||||
|
||||
**Before starting any work:**
|
||||
|
||||
- [ ] **Read CONTRIBUTING.md** - Found in root, .github/, or docs/
|
||||
- [ ] **Read CODE_OF_CONDUCT.md** - Understand community expectations
|
||||
- [ ] **Check if issue exists** - Search existing issues for your topic
|
||||
- [ ] **Create issue first (if needed)** - For significant changes, discuss before coding
|
||||
- [ ] **Comment on issue to claim work** - Prevents duplicate effort
|
||||
```
|
||||
"Hi! I'd like to work on this. My approach would be to [brief outline]."
|
||||
```
|
||||
- [ ] **Wait for acknowledgment** - Especially for large changes
|
||||
- [ ] **Fork the repository** - If you don't have write access
|
||||
- [ ] **Set up upstream remote**
|
||||
```bash
|
||||
git remote add upstream https://github.com/ORIGINAL/repo.git
|
||||
```
|
||||
- [ ] **Create feature branch** - NEVER work on main/master
|
||||
```bash
|
||||
git checkout -b feature/descriptive-name
|
||||
```
|
||||
- [ ] **Understand testing requirements** - Check what tests are expected
|
||||
- [ ] **Identify code style tools** - Look for .eslintrc, .prettierrc, etc.
|
||||
|
||||
---
|
||||
|
||||
## Development Phase
|
||||
|
||||
**While coding:**
|
||||
|
||||
- [ ] **Follow project style guidelines** - Match existing code patterns
|
||||
- [ ] **Write tests for new functionality** - Most projects require this
|
||||
- [ ] **Update tests for changed behavior** - Keep tests in sync with code
|
||||
- [ ] **Add/update documentation** - README, API docs, inline comments
|
||||
- [ ] **Keep commits atomic** - One logical change per commit
|
||||
- [ ] **Write good commit messages** - Follow Conventional Commits format
|
||||
```
|
||||
feat(scope): brief description
|
||||
|
||||
Longer explanation if needed
|
||||
|
||||
Fixes #123
|
||||
```
|
||||
- [ ] **Run linters and formatters** - Fix style issues during development
|
||||
```bash
|
||||
npm run lint
|
||||
npm run format
|
||||
```
|
||||
- [ ] **Test locally frequently** - Don't wait until the end
|
||||
- [ ] **Keep PR scope focused** - One feature/fix per PR
|
||||
- [ ] **Sync with upstream regularly** - Avoid merge conflicts
|
||||
```bash
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pre-Submission Phase
|
||||
|
||||
### Code Quality
|
||||
|
||||
- [ ] **All tests pass locally**
|
||||
```bash
|
||||
npm test
|
||||
# or
|
||||
pytest
|
||||
# or
|
||||
cargo test
|
||||
# or project's test command
|
||||
```
|
||||
- [ ] **Code builds successfully**
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
- [ ] **Linter passes**
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
- [ ] **Formatter applied**
|
||||
```bash
|
||||
npm run format
|
||||
```
|
||||
- [ ] **Code coverage maintained** - If project has minimum thresholds
|
||||
- [ ] **No compiler warnings** - Clean build output
|
||||
- [ ] **Manual testing completed** - Test the actual functionality
|
||||
|
||||
### Code Review (Self)
|
||||
|
||||
- [ ] **Review your own diff**
|
||||
```bash
|
||||
git diff origin/main
|
||||
```
|
||||
- [ ] **No debugging code** - Remove console.logs, debugger statements
|
||||
- [ ] **No commented-out code** - Remove dead code
|
||||
- [ ] **No TODO comments** - Complete work or create follow-up issues
|
||||
- [ ] **Consistent naming** - Variables, functions, files match conventions
|
||||
- [ ] **Proper error handling** - Don't swallow errors silently
|
||||
- [ ] **Edge cases considered** - Null checks, empty arrays, etc.
|
||||
|
||||
### Cleanup (Critical!)
|
||||
|
||||
Run the pre-PR check script:
|
||||
```bash
|
||||
./scripts/pre-pr-check.sh
|
||||
```
|
||||
|
||||
- [ ] **Remove SESSION.md** - Personal session tracking
|
||||
- [ ] **Remove NOTES.md** - Development notes
|
||||
- [ ] **Remove TODO.md** - Personal todo lists
|
||||
- [ ] **Remove planning/* directory** - Project planning documents
|
||||
- [ ] **Remove debug screenshots** - Screenshots used during debugging
|
||||
- Keep only screenshots demonstrating features for PR description
|
||||
- [ ] **Remove temporary test files**
|
||||
- test-manual.js, test-debug.ts, quick-test.py
|
||||
- [ ] **Remove personal workflow files**
|
||||
- scratch.*, temp.*, debug.*
|
||||
- [ ] **No IDE/editor files**
|
||||
- .vscode/, .idea/, *.swp
|
||||
- Should be in global .gitignore, not committed
|
||||
- [ ] **No OS-specific files**
|
||||
- .DS_Store, Thumbs.db, desktop.ini
|
||||
- [ ] **No build artifacts**
|
||||
- dist/, build/, node_modules/, __pycache__/
|
||||
- [ ] **No secrets or credentials**
|
||||
- .env, credentials.json, *.key, *.pem
|
||||
- Double-check with: `git diff | grep -i "password\|secret\|key"`
|
||||
- [ ] **No large binary files** - Unless necessary for the PR
|
||||
- [ ] **No unrelated changes** - Only changes relevant to this PR
|
||||
|
||||
### Git Hygiene
|
||||
|
||||
- [ ] **Commits are clean** - No "WIP" or "fix typo" commits
|
||||
- Consider squashing if needed
|
||||
- [ ] **Commit messages follow conventions** - Conventional Commits format
|
||||
- [ ] **No merge conflicts** - Rebase on latest upstream/main
|
||||
```bash
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
```
|
||||
- [ ] **Branch is up to date** - Latest changes from main included
|
||||
- [ ] **On feature branch** - Not on main/master
|
||||
|
||||
---
|
||||
|
||||
## PR Creation Phase
|
||||
|
||||
### PR Description
|
||||
|
||||
- [ ] **Title follows conventions** - Conventional Commits format
|
||||
```
|
||||
feat(auth): add OAuth2 support
|
||||
fix(api): resolve memory leak
|
||||
docs(readme): update installation
|
||||
```
|
||||
- [ ] **Uses What/Why/How structure**
|
||||
- What: Brief description of changes
|
||||
- Why: Reasoning and context
|
||||
- How: Implementation approach
|
||||
- [ ] **Testing instructions included** - Step-by-step how to test
|
||||
- [ ] **Screenshots for visual changes** - Before/after if applicable
|
||||
- [ ] **Breaking changes noted** - If any
|
||||
- [ ] **Links to related issues** - Use closing keywords
|
||||
```
|
||||
Closes #123
|
||||
Fixes #456
|
||||
Relates to #789
|
||||
```
|
||||
- [ ] **Checklist included** - Tests, docs, CI status
|
||||
- [ ] **Description is clear** - Reviewer can understand without asking questions
|
||||
|
||||
### PR Quality
|
||||
|
||||
- [ ] **PR is reasonably sized**
|
||||
- Ideal: < 50 lines
|
||||
- Good: < 200 lines
|
||||
- Max: < 400 lines
|
||||
- If larger, explain why or split into multiple PRs
|
||||
- [ ] **PR is focused** - One feature/fix/refactor, not multiple unrelated changes
|
||||
- [ ] **No unrelated changes** - No "drive-by fixes" in unrelated files
|
||||
- [ ] **All changed files are intentional** - Review git status
|
||||
|
||||
### GitHub Settings
|
||||
|
||||
- [ ] **Pushed to feature branch on fork**
|
||||
```bash
|
||||
git push origin feature/my-feature
|
||||
```
|
||||
- [ ] **PR targets correct branch** - Usually main or develop
|
||||
- [ ] **Assigned labels** - If you have permission
|
||||
- [ ] **Requested reviewers** - If known and appropriate
|
||||
- [ ] **Linked to project/milestone** - If applicable
|
||||
- [ ] **Set as draft** - If not ready for full review yet
|
||||
```bash
|
||||
gh pr create --draft
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Post-Submission Phase
|
||||
|
||||
### Monitor CI/Checks
|
||||
|
||||
- [ ] **CI is running** - Green checkmarks appearing
|
||||
- [ ] **All checks pass** - No failures
|
||||
- [ ] **Fix failures immediately** - Don't wait for review if CI fails
|
||||
- [ ] **Watch for build notifications** - Email/GitHub notifications
|
||||
|
||||
### Communication
|
||||
|
||||
- [ ] **Responsive to feedback** - Reply within 24-48 hours
|
||||
- [ ] **Address all review comments** - Even if just "Acknowledged"
|
||||
- [ ] **Mark conversations resolved** - After addressing feedback
|
||||
- [ ] **Request re-review** - After making changes
|
||||
```bash
|
||||
gh pr ready # if was draft
|
||||
```
|
||||
- [ ] **Thank reviewers** - Shows appreciation for their time
|
||||
- [ ] **Professional tone** - Courteous and respectful
|
||||
- [ ] **Ask for clarification** - If feedback is unclear
|
||||
- [ ] **Be patient** - Reviewers are often volunteers
|
||||
|
||||
### Updates
|
||||
|
||||
- [ ] **Keep PR updated** - Rebase if main moves forward
|
||||
```bash
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
git push origin feature/my-feature --force-with-lease
|
||||
```
|
||||
- [ ] **Fix requested changes** - Implement feedback
|
||||
- [ ] **Update documentation** - If requirements change
|
||||
- [ ] **Squash commits** - If maintainer requests
|
||||
|
||||
---
|
||||
|
||||
## Ready to Submit?
|
||||
|
||||
**Final verification:**
|
||||
|
||||
```bash
|
||||
# 1. Run pre-PR check
|
||||
./scripts/pre-pr-check.sh
|
||||
|
||||
# 2. Review changes
|
||||
git status
|
||||
git diff origin/main --stat
|
||||
|
||||
# 3. Verify tests pass
|
||||
npm test
|
||||
|
||||
# 4. Verify build succeeds
|
||||
npm run build
|
||||
|
||||
# 5. Check commit messages
|
||||
git log --oneline -5
|
||||
|
||||
# 6. Push to your fork
|
||||
git push origin feature/my-feature
|
||||
|
||||
# 7. Create PR
|
||||
gh pr create --fill
|
||||
# or
|
||||
gh pr create --title "feat: ..." --body "$(cat pr-description.md)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes Checklist
|
||||
|
||||
Avoid these common errors:
|
||||
|
||||
- [ ] ❌ Not reading CONTRIBUTING.md
|
||||
- [ ] ❌ Including personal artifacts (SESSION.md, planning/*)
|
||||
- [ ] ❌ Submitting massive PR (>400 lines)
|
||||
- [ ] ❌ Not testing before submission
|
||||
- [ ] ❌ Working on already assigned issue
|
||||
- [ ] ❌ Not discussing large changes first
|
||||
- [ ] ❌ Being impatient or unresponsive
|
||||
- [ ] ❌ Not updating documentation
|
||||
- [ ] ❌ Ignoring code style
|
||||
- [ ] ❌ Ignoring CI failures
|
||||
- [ ] ❌ Including unrelated changes
|
||||
- [ ] ❌ Not linking issues properly
|
||||
- [ ] ❌ Committing secrets
|
||||
- [ ] ❌ Force-pushing without warning
|
||||
- [ ] ❌ Working on main/master branch
|
||||
|
||||
---
|
||||
|
||||
## Project-Specific Checklist
|
||||
|
||||
Add project-specific items here based on CONTRIBUTING.md:
|
||||
|
||||
- [ ] _[Project-specific requirement 1]_
|
||||
- [ ] _[Project-specific requirement 2]_
|
||||
- [ ] _[Project-specific requirement 3]_
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Essential Commands
|
||||
|
||||
```bash
|
||||
# Setup
|
||||
git clone https://github.com/YOUR-USERNAME/repo.git
|
||||
git remote add upstream https://github.com/ORIGINAL/repo.git
|
||||
git checkout -b feature/my-feature
|
||||
|
||||
# Development
|
||||
npm run lint
|
||||
npm test
|
||||
npm run build
|
||||
git add .
|
||||
git commit -m "feat(scope): description"
|
||||
|
||||
# Pre-submission
|
||||
./scripts/pre-pr-check.sh
|
||||
git status
|
||||
git diff origin/main
|
||||
|
||||
# Submission
|
||||
git push origin feature/my-feature
|
||||
gh pr create --fill
|
||||
|
||||
# After feedback
|
||||
git fetch upstream
|
||||
git rebase upstream/main
|
||||
# make changes
|
||||
git push origin feature/my-feature --force-with-lease
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **Pre-PR Check Script**: `./scripts/pre-pr-check.sh`
|
||||
- **Clean Branch Script**: `./scripts/clean-branch.sh`
|
||||
- **PR Template**: `./references/pr-template.md`
|
||||
- **Commit Message Guide**: `./references/commit-message-guide.md`
|
||||
- **Files to Exclude**: `./references/files-to-exclude.md`
|
||||
|
||||
---
|
||||
|
||||
**Remember**: The goal is to make the maintainer's job as easy as possible. A well-prepared PR shows respect for their time and increases the likelihood of quick acceptance.
|
||||
Reference in New Issue
Block a user