zhongwei/gh-jezweb-claude-skills-skills-open-source-contributions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:25:07 +08:00
commit f613de7a1a
13 changed files with 4333 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "open-source-contributions",
"description": "Create maintainer-friendly pull requests for open source projects with clean code submissions and professional communication. Prevents 16 common mistakes that cause PR rejection. Use when: contributing to public repositories, submitting PRs to community projects, migrating from contributor to maintainer workflows, or troubleshooting PR rejection, working on main branch errors, failing CI checks, or personal artifacts in commits.",
"version": "1.0.0",
"author": {
"name": "Jeremy Dawes",
"email": "jeremy@jezweb.net"
},
"skills": [
"./"
]
}

21
LICENSE Normal file
View File

@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2025 Jeremy Dawes - Jezweb
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# open-source-contributions
Create maintainer-friendly pull requests for open source projects with clean code submissions and professional communication. Prevents 16 common mistakes that cause PR rejection. Use when: contributing to public repositories, submitting PRs to community projects, migrating from contributor to maintainer workflows, or troubleshooting PR rejection, working on main branch errors, failing CI checks, or personal artifacts in commits.

1233
SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff

552
assets/bad-pr-example.md Normal file
View File

@@ -0,0 +1,552 @@
# Bad PR Example
This example demonstrates common mistakes that annoy maintainers and lead to PR rejection or delays. Learn what NOT to do!
---
## Example: Adding OAuth2 Authentication (Done Wrong)
### PR Title ❌
```
Updated code
```
**Why it's bad:**
- ❌ Too vague
- ❌ Doesn't describe what changed
- ❌ No type prefix (feat/fix/docs)
- ❌ Wrong tense (past instead of imperative)
- ❌ Lowercase (should capitalize)
**Should be:**
```
feat(auth): add OAuth2 support for Google and GitHub providers
```
---
### PR Description ❌
```markdown
## Changes
Added OAuth
## Testing
Works for me
```
**Why it's bad:**
- ❌ No explanation of WHAT was added
- ❌ No explanation of WHY it's needed
- ❌ No explanation of HOW it works
- ❌ No testing instructions for reviewers
- ❌ No issue links
- ❌ No screenshots
- ❌ "Works for me" is not helpful
**Result:** Maintainer has to ask multiple questions before even starting review.
---
### Files Changed (Messy!) ❌
```
.env # ❌ SECRETS COMMITTED!
.vscode/settings.json # ❌ Personal IDE config
SESSION.md # ❌ Personal development notes
planning/oauth-implementation.md # ❌ Planning documents
screenshots/debug-oauth-1.png # ❌ Debug screenshots
screenshots/debug-oauth-2.png # ❌ Debug screenshots
screenshots/test-local.png # ❌ Personal testing screenshots
test-manual.js # ❌ Temporary test file
NOTES.md # ❌ Personal notes
TODO.md # ❌ Personal todo list
node_modules/ # ❌ Dependencies (should be in .gitignore!)
package-lock.json # ❌ Lock file changes (not needed)
src/routes/auth.js # ✅ Actual feature code
src/routes/users.js # ❌ Unrelated changes
src/routes/posts.js # ❌ Unrelated changes
src/components/Header.js # ❌ Unrelated changes
src/utils/formatting.js # ❌ Unrelated refactoring
README.md # ✅ Documentation update
docs/authentication.md # ✅ OAuth documentation
```
**Problems:**
- ❌ **28 files changed** (way too many!)
- ❌ **Secrets committed** (.env file with API keys)
- ❌ **Personal artifacts** (SESSION.md, NOTES.md, planning/)
- ❌ **Unrelated changes** (users.js, posts.js, Header.js)
- ❌ **Mixed concerns** (feature + refactoring + bug fixes)
**Should be:** 5-8 files, only those directly related to OAuth feature.
---
### Commit History (Terrible!) ❌
```
WIP
fixed stuff
asdf
more changes
fix
actually working now
Final commit
Actually final
OK this one is final
oops forgot something
```
**Why it's bad:**
- ❌ 10 commits for one feature (should squash)
- ❌ Meaningless commit messages
- ❌ "WIP" commits (not production-ready)
- ❌ No explanation of what changed
- ❌ No issue links
- ❌ Commit history shows trial-and-error (should clean up)
**Should be:** 1-2 clean commits with proper messages.
---
### SESSION.md Content (Should Never Be Committed!) ❌
```markdown
# OAuth Implementation Session
## 2025-11-04
Started working on OAuth. Not sure if I should use passport or just implement it myself. Going to try passport first.
## 2025-11-05
Passport is confusing. Spent 3 hours debugging. Finally got it working but the code is messy.
TODO:
- Clean up the callback logic
- Add tests (maybe)
- Figure out how to handle errors
- Ask @maintainer about rate limiting?
NOTES:
- Google OAuth app ID: 123456789-abcdefgh.apps.googleusercontent.com
- Redirect URI: http://localhost:3000/auth/google/callback
- Remember to add to staging: https://staging.myapp.com/auth/google/callback
BUGS FOUND:
- Header component has alignment issue on mobile
- Post creation form doesn't validate correctly
- User profile page crashes when avatar is null
```
**Why this should NEVER be in a PR:**
- ❌ Personal development journal
- ❌ Reveals your confusion/struggle
- ❌ Contains unfinished TODOs
- ❌ Mentions unrelated bugs
- ❌ Unprofessional appearance
- ❌ Pollutes the project
---
### NOTES.md Content (Should Never Be Committed!) ❌
```markdown
# Development Notes
## OAuth Research
Looked at how GitHub and GitLab do OAuth. Their implementations are pretty complex. Mine is simpler.
## Design Decisions
- Using passport because it's easier
- Not implementing token refresh yet (can do later)
- Rate limiting - should probably add this but skipping for now
- Testing - added some tests but not complete coverage
## Things I'm Not Sure About
- Is the error handling good enough?
- Should I use sessions or JWT?
- Do I need to validate the email from OAuth providers?
## Known Issues
- Doesn't work in Safari (CORS issue)
- Memory leak in callback handler (need to fix)
- Missing rate limiting (security risk?)
```
**Why this hurts your PR:**
- ❌ Shows incomplete work
- ❌ Admits to known issues not mentioned in PR
- ❌ Reveals security concerns not addressed
- ❌ Makes maintainer lose confidence
- ❌ Creates more work for maintainer
---
### Communication During Review ❌
**Initial Comment:**
```
Here's my OAuth implementation. Let me know what you think.
```
**Why it's bad:**
- ❌ No context
- ❌ No explanation
- ❌ No testing instructions
- ❌ Sounds careless
---
**Response to Feedback (Poor):**
**Maintainer:** "Could you add tests for the error cases?"
**Bad Response:**
```
Tests are boring. The code works fine without them.
```
**Why it's bad:**
- ❌ Dismissive
- ❌ Unprofessional
- ❌ Doesn't follow project standards
- ❌ Shows lack of respect
---
**Maintainer:** "This PR is too large. Could you split it into smaller PRs?"
**Bad Response:**
```
It's all related though. I don't want to spend time splitting it up.
```
**Why it's bad:**
- ❌ Refuses reasonable request
- ❌ Doesn't consider reviewer's time
- ❌ Makes review harder
- ❌ Likely to be closed
---
**No Response for 2 Weeks** ❌
**Maintainer:** "The tests are failing. Can you fix them?"
**Your response:** [Silence for 2 weeks]
**Why it's bad:**
- ❌ Wastes maintainer's time
- ❌ PR goes stale
- ❌ Likely to be closed
- ❌ Damages your reputation
---
### PR Metrics ❌
**Size:**
- Lines changed: 847
- Files changed: 28
- Commits: 10
**Problems:**
- ❌ Way too large (should be <200 lines)
- ❌ Too many files (includes unrelated changes)
- ❌ Messy commit history
**Timeline:**
- Submitted: Day 1
- Maintainer requests changes: Day 2
- No response: Days 3-16
- PR closed as stale: Day 17
---
## Specific Mistakes Breakdown
### 1. Committed Secrets ❌
**.env file contents:**
```
GOOGLE_CLIENT_ID=123456789-abcdefgh.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-abc123def456 # ❌ SECRET!
GITHUB_CLIENT_ID=Iv1.1234567890abcdef
GITHUB_CLIENT_SECRET=1234567890abcdef1234567890abcdef12345678 # ❌ SECRET!
DATABASE_URL=postgresql://admin:SuperSecret123@localhost/myapp # ❌ PASSWORD!
```
**Impact:**
- 🚨 Security breach!
- 🚨 Must rotate all secrets immediately
- 🚨 Potentially compromises production
- 🚨 Even if removed later, it's in git history
**What you should have done:**
- ✅ Only commit .env.example with placeholder values
- ✅ Add .env to .gitignore
- ✅ Never commit actual secrets
---
### 2. Including Unrelated Changes ❌
**src/routes/users.js:**
```javascript
// OAuth PR includes this "drive-by fix"
exports.getUser = async (req, res) => {
const user = await User.findById(req.params.id);
// Fixed bug where avatar URL was broken
if (user.avatar) {
user.avatar = user.avatar.replace('http://', 'https://');
}
res.json(user);
};
```
**Why it's bad:**
- ❌ Not related to OAuth feature
- ❌ Makes PR harder to review
- ❌ Mixed concerns
- ❌ If PR is reverted, this fix goes too
**What you should have done:**
- ✅ Create separate PR for bug fix
- ✅ Keep OAuth PR focused on OAuth only
---
### 3. Massive PR with No Breakdown ❌
**Includes all at once:**
- OAuth implementation (200 lines)
- Refactoring of existing auth (300 lines)
- Bug fixes in unrelated files (150 lines)
- UI updates (100 lines)
- Test updates (97 lines)
**Total: 847 lines in 28 files**
**Why it's bad:**
- ❌ Takes hours to review
- ❌ Hard to find bugs
- ❌ Difficult to discuss
- ❌ Can't merge incrementally
**What you should have done:**
- ✅ PR #1: Refactor existing auth (300 lines)
- ✅ PR #2: Add OAuth backend (200 lines)
- ✅ PR #3: Add OAuth UI (100 lines)
- ✅ PR #4: Fix related bugs (150 lines)
---
### 4. Poor Testing ❌
**test-manual.js (Committed by mistake!):**
```javascript
// Quick test script - DELETE BEFORE COMMIT!
const axios = require('axios');
async function testOAuth() {
// This only works on my machine
const response = await axios.get('http://localhost:3000/auth/google');
console.log('Works!');
}
testOAuth();
```
**Why it's bad:**
- ❌ Not a proper test
- ❌ Hardcoded localhost
- ❌ No assertions
- ❌ Comment says "DELETE BEFORE COMMIT"
- ❌ Clutters project
**What you should have done:**
- ✅ Delete this file
- ✅ Write proper tests in tests/auth/oauth.test.js
- ✅ Use project's testing framework
- ✅ Include assertions and edge cases
---
### 5. Missing Documentation ❌
**README.md changes:**
```markdown
## Authentication
We now have OAuth.
```
**Why it's bad:**
- ❌ No setup instructions
- ❌ No explanation of how it works
- ❌ No examples
- ❌ Unhelpful to users
**Should be:**
```markdown
## Authentication
### OAuth 2.0 Social Login
Users can sign in with Google or GitHub accounts.
#### Setup
1. Create OAuth apps:
- Google: https://console.cloud.google.com/apis/credentials
- GitHub: https://github.com/settings/developers
2. Add credentials to `.env`:
```
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
```
3. Restart server
#### Usage
Users will see "Sign in with Google" and "Sign in with GitHub" buttons on the login page.
For detailed implementation, see [docs/authentication.md](docs/authentication.md).
```
---
### 6. Ignoring CI Failures ❌
**CI Status:**
```
❌ Tests: 5 failing
❌ Lint: 23 errors
❌ Build: Failed
```
**Your response:** Submit PR anyway, hope maintainer doesn't notice
**Why it's bad:**
- ❌ Shows you didn't test
- ❌ Wastes CI resources
- ❌ Can't merge with failing CI
- ❌ Unprofessional
**What you should have done:**
- ✅ Fix all CI issues before submitting
- ✅ Run tests locally first: `npm test`
- ✅ Run lint locally: `npm run lint`
- ✅ Only submit when all checks pass
---
## The Result
**Maintainer's Response:**
```
Thanks for the PR, but there are several issues:
1. You've committed secrets in the .env file - this is a security issue
2. The PR includes unrelated changes (users.js, posts.js, Header.js)
3. Personal development files (SESSION.md, NOTES.md, planning/) shouldn't be here
4. The PR is too large - 847 lines across 28 files
5. Tests are failing
6. Missing proper documentation
7. test-manual.js is committed
Please:
- Remove all secrets and rotate them
- Create separate PRs for unrelated changes
- Remove personal development artifacts
- Fix the failing tests
- Add proper documentation
- Keep the PR focused on OAuth only
I'm closing this for now. Please feel free to submit a new PR addressing these issues.
```
**Status:** ❌ PR Closed
---
## Key Lessons
### What Went Wrong
1. **Security**: Committed secrets (.env file)
2. **Scope**: Too large, too many unrelated changes
3. **Artifacts**: Personal files committed (SESSION.md, NOTES.md)
4. **Testing**: Poor testing, CI failures
5. **Documentation**: Inadequate documentation
6. **Communication**: Poor responses to feedback
7. **Quality**: Messy commits, no code review
8. **Professionalism**: Dismissive attitude
### How to Fix It
1. **Security**
- Never commit secrets
- Use .env.example with placeholders
- Run pre-PR check script
2. **Scope**
- Keep PRs small (<200 lines)
- One feature per PR
- No unrelated changes
3. **Artifacts**
- Remove SESSION.md, NOTES.md, TODO.md
- Remove planning/ directory
- Remove debug screenshots
- Use clean-branch script
4. **Testing**
- Write proper tests
- Fix CI before submitting
- Test locally first
5. **Documentation**
- Update README
- Add setup instructions
- Include examples
6. **Communication**
- Be responsive
- Be respectful
- Accept feedback gracefully
7. **Quality**
- Clean commit history
- Proper commit messages
- Review your own code
8. **Professionalism**
- Respect maintainer's time
- Follow project conventions
- Be patient and courteous
---
## Comparison: Bad vs Good
| Aspect | Bad PR ❌ | Good PR ✅ |
|--------|-----------|-----------|
| **Title** | "Updated code" | "feat(auth): add OAuth2 support" |
| **Size** | 847 lines, 28 files | 180 lines, 9 files |
| **Commits** | 10 messy commits | 1 clean commit |
| **Files** | Includes SESSION.md, .env | Only relevant files |
| **Testing** | test-manual.js, CI failing | Proper tests, CI passing |
| **Docs** | "We now have OAuth" | Complete setup guide |
| **Secrets** | Committed .env | Only .env.example |
| **Scope** | OAuth + bugs + refactor | OAuth only |
| **Communication** | Dismissive | Professional |
| **Result** | Closed | Merged in 3 days |
---
**Remember:** Every mistake in this example is based on real PRs that have been rejected. Learn from these errors and follow the good PR example instead!

308
assets/good-pr-example.md Normal file
View File

@@ -0,0 +1,308 @@
# Good PR Example
This example demonstrates a well-structured pull request that follows best practices for open source contributions.
---
## Example: Adding OAuth2 Authentication
### PR Title
```
feat(auth): add OAuth2 support for Google and GitHub providers
```
**Why it's good:**
- ✅ Uses Conventional Commits format (feat)
- ✅ Includes scope (auth)
- ✅ Clear, specific description
- ✅ Under 50 characters
- ✅ Imperative mood
---
### PR Description
```markdown
## What?
Add OAuth2 authentication support for Google and GitHub providers, allowing users to sign in with their social accounts.
## Why?
Multiple users have requested social login to reduce friction during signup (issues #234, #156). This addresses a key pain point: 40% of attempted signups are abandoned at the password creation step according to our analytics.
This implements Key Result 2 of Q4 OKR1: "Reduce signup friction by 30%"
## How?
- Implemented OAuth2 flow using passport.js strategy pattern
- Added provider configuration via environment variables (no hardcoded secrets)
- Created callback routes for each provider:
- `/auth/google/callback`
- `/auth/github/callback`
- Updated user model to link social accounts with existing email-based accounts
- Added middleware to automatically merge accounts if user already exists with same email
- Implemented proper error handling for failed OAuth attempts
## Testing
### Setup
1. Create OAuth apps in developer consoles:
- Google: https://console.cloud.google.com/apis/credentials
- GitHub: https://github.com/settings/developers
2. Add credentials to `.env` file (see `.env.example` for required variables)
3. Run `npm install` to ensure passport dependencies are installed
### Manual Testing Steps
1. Start server: `npm start`
2. Navigate to `http://localhost:3000/login`
3. Click "Login with Google" button
4. Verify OAuth flow redirects to Google consent screen
5. Grant permissions
6. Verify redirect back to app with user logged in
7. Check user profile shows data from Google (name, email, avatar)
8. Repeat steps 3-7 for GitHub provider
### Test Cases Covered
- ✅ New user signup via OAuth
- ✅ Existing user login via OAuth
- ✅ Account merging (same email, different provider)
- ✅ Error handling (user denies permissions)
- ✅ Error handling (OAuth provider timeout)
- ✅ Security: CSRF token validation
### Automated Tests
```bash
npm test -- tests/auth/oauth.test.js
```
All 15 test cases pass, including edge cases.
## Checklist
- [x] Tests added/updated (tests/auth/oauth.test.js)
- [x] Documentation updated:
- [x] README.md (setup instructions)
- [x] docs/authentication.md (OAuth flow documentation)
- [x] .env.example (required environment variables)
- [x] CI passing (all checks green)
- [x] No breaking changes
- [x] Follows existing code style
- [x] Security review completed (no secrets committed)
## Related Issues
Closes #234
Relates to #156 (social login epic)
## Screenshots
### Login Page with OAuth Buttons
![OAuth Login Buttons](./screenshots/oauth-buttons.png)
*New social login buttons integrated into existing login page*
### OAuth Consent Screen (Google)
![Google Consent](./screenshots/google-consent.png)
*User experience during Google OAuth flow*
## Breaking Changes
None - this is additive functionality that doesn't affect existing authentication methods.
## Security Considerations
- OAuth tokens are stored securely using bcrypt hashing
- CSRF protection implemented for all OAuth routes
- State parameter used to prevent CSRF attacks
- No secrets committed to repository (all in .env)
- Rate limiting applied to OAuth endpoints
## Additional Notes
### Design Decisions
- **Chose passport.js** over custom implementation for security, maintenance, and community support
- **Used strategy pattern** to make adding new OAuth providers easier in future
- **Account merging** happens automatically based on email address (primary key)
- **No email verification required** for OAuth signups (providers already verify emails)
### Future Improvements
Consider in follow-up PRs:
- Add more providers (Twitter, LinkedIn, Microsoft)
- Implement OAuth token refresh logic
- Add rate limiting for OAuth endpoints
- Add admin dashboard for managing OAuth apps
### Migration Notes
No migration needed - existing users can continue using password authentication. OAuth is an additional option.
### Dependencies Added
- passport v0.6.0
- passport-google-oauth20 v2.0.0
- passport-github2 v0.1.12
All dependencies are actively maintained and have good security track records.
```
---
### Files Changed (Clean!)
```
.env.example # Environment variable examples (no secrets!)
README.md # Updated setup instructions
docs/authentication.md # OAuth documentation
package.json # Added passport dependencies
src/routes/auth.js # OAuth routes
src/middleware/authenticate.js # OAuth middleware
src/models/user.js # Updated user model
tests/auth/oauth.test.js # OAuth tests
tests/fixtures/users.json # Test fixtures
```
**What's NOT included:**
- ❌ No SESSION.md or notes files
- ❌ No planning/ directory
- ❌ No debug screenshots (only feature demos)
- ❌ No temporary test files
- ❌ No .env file (only .env.example)
- ❌ No personal artifacts
---
### Commit History (Clean!)
```
feat(auth): add OAuth2 support for Google and GitHub
Implemented OAuth2 authentication flow using passport.js.
Users can now sign in with Google or GitHub accounts.
Accounts are automatically merged if email matches existing user.
- Added OAuth routes and callbacks
- Updated user model to support social accounts
- Added comprehensive tests for OAuth flow
- Documented setup and usage
Closes #234
```
**Why it's good:**
- ✅ Single, focused commit
- ✅ Clear commit message
- ✅ Explains what and why
- ✅ Links issue
- ✅ Follows Conventional Commits
---
### Communication During Review
**Initial Comment (When Submitting):**
```
Hi @maintainer! 👋
I've implemented OAuth2 support as discussed in #234. I went with passport.js over a custom implementation because:
1. Battle-tested security
2. Well-maintained by the community
3. Easy to add more providers in future
I've tested this locally for the past week and also deployed to staging for integration testing. All existing auth flows remain unchanged - this is purely additive.
Ready for review when you have time! Happy to make any changes you'd like.
```
**Response to Feedback:**
```
> Could you add rate limiting to these endpoints?
Good idea! I've added rate limiting in commit abc1234:
- Max 5 OAuth attempts per IP per minute
- Returns 429 with Retry-After header
- Uses existing rate limiting middleware
Let me know if you'd prefer different limits!
```
**After Changes:**
```
@maintainer I've addressed all your feedback:
- ✅ Added rate limiting (commit abc1234)
- ✅ Updated docs with security considerations (commit def5678)
- ✅ Refactored callback logic as suggested (commit ghi9012)
Marked all conversations as resolved. Ready for re-review!
Thanks for the thorough feedback - the rate limiting suggestion was spot-on.
```
---
### PR Metrics
**Size:**
- Lines changed: 180
- Files changed: 9
- Commits: 1
**Result:**
- ✅ Ideal size for review
- ✅ Focused on one feature
- ✅ Easy to understand
- ✅ Quick to review
**Timeline:**
- Submitted: Day 1
- First review: Day 2
- Changes made: Day 2
- Approved: Day 3
- Merged: Day 3
**Why it was quick:**
- Clean, focused PR
- Comprehensive testing
- Good documentation
- Responsive to feedback
- No surprises or issues
---
## Key Takeaways
This PR demonstrates:
1. **Clear Communication**
- What/Why/How structure
- Testing instructions
- Design decisions explained
- Security considerations noted
2. **Proper Scope**
- One feature
- ~180 lines changed
- No unrelated changes
- Easy to review
3. **Complete Documentation**
- Updated README
- Added OAuth docs
- Included .env.example
- Comprehensive inline comments
4. **Thorough Testing**
- Automated tests
- Manual test steps
- Edge cases covered
- Deployed to staging first
5. **Professional Artifacts**
- No personal files
- No secrets
- Clean commit history
- Proper branch naming
6. **Excellent Communication**
- Polite and respectful
- Responsive to feedback
- Explains decisions
- Thanks reviewers
7. **Security Conscious**
- No secrets committed
- CSRF protection
- Rate limiting
- Security considerations documented
This is the standard to aim for in your pull requests!

81
plugin.lock.json Normal file
View File

@@ -0,0 +1,81 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:jezweb/claude-skills:skills/open-source-contributions",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "7ae82902e2041f78650cf6c998468d6077cb54b2",
"treeHash": "a5ed0be3adad9b9e436d1b851f17d92f37cda3323b14344a4902f39c4d4d26c2",
"generatedAt": "2025-11-28T10:19:05.922861Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "open-source-contributions",
"description": "Create maintainer-friendly pull requests for open source projects with clean code submissions and professional communication. Prevents 16 common mistakes that cause PR rejection. Use when: contributing to public repositories, submitting PRs to community projects, migrating from contributor to maintainer workflows, or troubleshooting PR rejection, working on main branch errors, failing CI checks, or personal artifacts in commits.",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "LICENSE",
"sha256": "b76f0805c81dad30acd0fa7aca893e4f834986e168549201c42a92e810956072"
},
{
"path": "README.md",
"sha256": "bc84341ca3867a7d42dd9d89d8eaa0326b6f9a76de91fb6a31d50895f53885b1"
},
{
"path": "SKILL.md",
"sha256": "1d6898ec2795b969f4768a253e4ac5780193f69ac34a291ae479531276698ede"
},
{
"path": "references/commit-message-guide.md",
"sha256": "99de91dcfbc148f82c1c31bd2d115a13863a113e287249abe4c1de93cddf0fea"
},
{
"path": "references/files-to-exclude.md",
"sha256": "296fd9310d53d57c48654e1e13876b8fe0e2c5d11da8d5bf51cc8f923e8bc82a"
},
{
"path": "references/pr-template.md",
"sha256": "cb077517e050d9610bf6fe83a7bb00767513be46d218f223d3beaee5a7b7b4a4"
},
{
"path": "references/pr-checklist.md",
"sha256": "69ba9e481e6e6209fc4d17fea8588886eb0634f8978daaa76fc3b59b3c542b42"
},
{
"path": "scripts/pre-pr-check.sh",
"sha256": "6e21d0c55651921b270f166f7cbbea244f0578506d78f984663c0c83497b4587"
},
{
"path": "scripts/clean-branch.sh",
"sha256": "0183418de9c4414aa40006a7a26f9c6ee04cade92de5eefe1bc5b5d1110e372c"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "0a0aa15f64627b970f0ca3b0bbf86390474a0994d963971ff72c438714d61434"
},
{
"path": "assets/good-pr-example.md",
"sha256": "11cf4e7376469c5bc334b54936fb794ecaffe5b09d9deaa857b832fb54a51d5c"
},
{
"path": "assets/bad-pr-example.md",
"sha256": "29cdd1bc4f676062dacf397342b366c08eb61f8637fb06ac08641436b4be3ab0"
}
],
"dirSha256": "a5ed0be3adad9b9e436d1b851f17d92f37cda3323b14344a4902f39c4d4d26c2"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

534
references/commit-message-guide.md Normal file
View File

@@ -0,0 +1,534 @@
# Commit Message Guide
A comprehensive guide to writing clear, consistent, and maintainable commit messages using the Conventional Commits format.
---
## Why Good Commit Messages Matter
- **Documentation**: Git history becomes a changelog
- **Code Review**: Easier to understand what changed and why
- **Debugging**: Quickly find when bugs were introduced
- **Automation**: Enables automatic changelog generation and versioning
- **Professionalism**: Shows attention to detail and respect for maintainers
---
## Conventional Commits Format
```
<type>(<scope>): <subject>
[optional body]
[optional footer(s)]
```
### Components
**Type** (required): Category of change
**Scope** (optional): What section of codebase is affected
**Subject** (required): Brief description of change
**Body** (optional): Detailed explanation
**Footer** (optional): Issue references, breaking changes
---
## Types
### Primary Types
**feat**: New feature for the user
```
feat(auth): add OAuth2 support for Google and GitHub
```
**fix**: Bug fix for the user
```
fix(api): resolve memory leak in worker shutdown
```
**docs**: Documentation changes only
```
docs(readme): update installation instructions for v2.0
```
**style**: Code style changes (formatting, missing semicolons, etc.)
```
style(components): format code with Prettier
```
**refactor**: Code change that neither fixes bug nor adds feature
```
refactor(auth): extract middleware to separate module
```
**perf**: Performance improvement
```
perf(database): add index to user_id column
```
**test**: Adding or updating tests
```
test(auth): add OAuth flow integration tests
```
### Supporting Types
**build**: Changes to build system or dependencies
```
build(deps): upgrade React to v18.2.0
```
**ci**: CI configuration changes
```
ci(github): add automated release workflow
```
**chore**: Other changes that don't modify src or test files
```
chore(deps): update dev dependencies
```
**revert**: Revert a previous commit
```
revert: feat(auth): add OAuth2 support
This reverts commit abc123def456.
```
---
## Subject Line Rules
### The 7 Rules
1. **Limit to 50 characters** (hard limit: 72)
2. **Use imperative mood** ("Add" not "Added" or "Adds")
3. **Capitalize first word** after the colon
4. **Don't end with punctuation**
5. **Focus on WHAT changed** (body explains WHY)
6. **Be specific** but concise
7. **Start with type** (if using Conventional Commits)
### Examples
✅ **Good:**
```
feat(api): add user authentication endpoint
fix(ui): resolve button alignment on mobile
docs(contributing): clarify PR submission process
refactor(utils): simplify date formatting logic
```
❌ **Bad:**
```
Fixed stuff # Too vague
Added new feature to the authentication system that allows users to login with OAuth # Too long
updated code # Not specific, wrong tense
feat(api): add user authentication. # Don't end with period
Feat(api): add auth # Don't capitalize type
```
---
## Optional Scope
The scope provides context about what part of the codebase changed.
### Common Scopes
```
feat(auth): ... # Authentication
feat(api): ... # API layer
feat(ui): ... # User interface
feat(database): ... # Database
feat(docs): ... # Documentation
feat(tests): ... # Tests
fix(deps): ... # Dependencies
build(webpack): ... # Build tooling
```
### Project-Specific Scopes
Check the project's recent commits for conventions:
```bash
git log --oneline -20
```
### When to Omit Scope
Scope is optional. Omit when:
- Change affects multiple areas
- Project doesn't use scopes
- Scope would be too generic
```
feat: add dark mode support
docs: update README
```
---
## Body (Optional)
The body provides detailed explanation of WHAT and WHY (code shows HOW).
### Rules
- Separate from subject with blank line
- Wrap at 72 characters per line
- Explain motivation and context
- Contrast with previous behavior
- Use bullet points for multiple points
### Example
```
feat(api): add rate limiting to authentication endpoints
Users can now make up to 100 authentication attempts per hour
per IP address. This prevents brute force attacks while allowing
legitimate users to retry failed login attempts.
Implementation details:
- Uses Redis for distributed rate limiting
- Configurable via RATE_LIMIT_MAX environment variable
- Returns 429 status with Retry-After header when exceeded
- Resets hourly at top of the hour
Previous behavior allowed unlimited attempts, which was identified
as a security vulnerability in audit #456.
```
### When to Include Body
Include a body when:
- Change is complex or non-obvious
- Design decisions need explanation
- Previous behavior needs context
- Multiple related changes in one commit
- Security or performance implications
### When to Skip Body
Skip the body when:
- Change is self-explanatory
- Subject line tells the complete story
- Trivial changes (typos, formatting)
---
## Footer (Optional)
Footers provide metadata about the commit.
### Breaking Changes
Use `BREAKING CHANGE:` footer for breaking changes:
```
feat(api)!: change authentication endpoint path
BREAKING CHANGE: The authentication endpoint has moved from
/api/auth to /api/v2/auth. Update your API calls accordingly.
Migration guide available at docs/migration/v2.md
```
Note the `!` after the type indicates a breaking change.
### Issue References
Link issues using keywords for automatic closing:
```
fix(ui): resolve mobile layout issues
Fixes #123
Closes #456, #789
Relates to #234
```
**Closing Keywords:**
- `Closes #123`
- `Fixes #123`
- `Resolves #123`
- Also: close, fix, resolve (case insensitive)
### Co-authored-by
Credit co-authors:
```
feat(api): add GraphQL support
Co-authored-by: Jane Doe <jane@example.com>
Co-authored-by: John Smith <john@example.com>
```
### Other Footers
```
Reviewed-by: Name <email>
Signed-off-by: Name <email>
Acked-by: Name <email>
See-also: #123
```
---
## Complete Examples
### Example 1: Simple Feature
```
feat(ui): add dark mode toggle
Adds a toggle button in settings to switch between light and dark
themes. User preference is saved to localStorage and persists
across sessions.
Closes #234
```
### Example 2: Bug Fix
```
fix(api): prevent race condition in cache invalidation
The cache invalidation logic wasn't thread-safe, causing occasional
race conditions when multiple workers tried to invalidate the same
key simultaneously.
Solution:
- Added mutex locks around the critical section
- Implemented timeout for lock acquisition (5s)
- Added retry logic with exponential backoff
- Updated tests to verify thread-safety
Fixes #456
```
### Example 3: Breaking Change
```
feat(api)!: migrate to TypeScript and update endpoint contracts
BREAKING CHANGE: All API endpoints now return ISO 8601 date
strings instead of Unix timestamps. Update client code to parse
dates accordingly.
Additionally, authentication now requires JWT tokens in the
Authorization header instead of session cookies.
Migration guide: docs/migration/v3.md
Closes #567
```
### Example 4: Refactoring
```
refactor(auth): extract middleware to separate module
No functional changes, but auth logic is now easier to test and
maintain. Consolidated duplicate code from 5 route handlers into
reusable middleware functions.
Files affected:
- New: middleware/authenticate.js
- Updated: routes/*.js (5 files)
- Tests: tests/middleware/auth.test.js
Relates to #301 (technical debt epic)
```
### Example 5: Documentation
```
docs(api): add examples for authentication flows
Added code examples for:
- Basic authentication with username/password
- OAuth2 flow with Google
- API key authentication
- JWT token refresh
Examples include curl commands and JavaScript fetch() snippets.
Closes #678
```
### Example 6: Multiple Related Changes
```
fix(auth): resolve multiple OAuth edge cases
- Handle expired refresh tokens gracefully
- Prevent account linking when email doesn't match
- Add rate limiting to token refresh endpoint
- Log failed OAuth attempts for security monitoring
Each issue was related to OAuth implementation and fixing them
separately would have caused merge conflicts.
Fixes #123, #456, #789
```
---
## Tips for Writing Good Commit Messages
### Do:
✅ Write in imperative mood ("Add" not "Added")
```
feat: add user profile page
```
✅ Be specific about what changed
```
fix(api): resolve timeout in user search endpoint
```
✅ Explain WHY in the body
```
refactor(db): switch to connection pooling
The previous approach created a new connection for each request,
which caused performance issues under load. Connection pooling
reduces overhead and improves response times by 40%.
```
✅ Use the body for complex changes
✅ Reference issues and PRs
✅ Follow project conventions
### Don't:
❌ Use past tense
```
feat: added user profile page ❌
```
❌ Be vague
```
fix: bug fix ❌
update: changes ❌
```
❌ Write novels in the subject line
```
feat(api): add new user authentication endpoint with OAuth2 support for Google and GitHub that also includes rate limiting ❌
```
❌ Skip the type (if project uses Conventional Commits)
```
Add user profile page ❌
```
❌ Use abbreviations or jargon unnecessarily
```
fix(db): rm dup recs via opt idx ❌
```
❌ Combine unrelated changes in one commit
```
feat: add dark mode, fix typo in README, update dependencies ❌
```
---
## Real-World Examples from Popular Projects
### React
```
feat(react-dom): Add support for CSS Layers
Implements support for @layer, enabling better CSS encapsulation.
Fixes #24556
```
### Node.js
```
doc: add missing types to request and response
Added TypeScript type definitions for several Request and Response
methods that were previously missing from the declarations.
Fixes: #12345
Refs: #67890
```
### Kubernetes
```
fix: prevent pod creation with invalid security context
Adds validation to reject pods with both `runAsUser: 0` and
`allowPrivilegeEscalation: false`, which is an invalid combination.
Closes #12345
```
---
## Commit Message Checklist
Before committing, verify:
- [ ] Type is correct (feat, fix, docs, etc.)
- [ ] Subject line under 50 characters (max 72)
- [ ] Imperative mood ("Add" not "Added")
- [ ] First word capitalized
- [ ] No period at end
- [ ] Body explains WHY (if needed)
- [ ] Body wrapped at 72 characters
- [ ] Blank line between subject and body
- [ ] Issues referenced in footer
- [ ] Breaking changes noted with BREAKING CHANGE:
- [ ] Follows project conventions
---
## Tools & Automation
### Commitizen
Interactive tool for writing commits:
```bash
npm install -g commitizen
git cz
```
### Commitlint
Lint commit messages:
```bash
npm install --save-dev @commitlint/cli @commitlint/config-conventional
```
### Husky
Git hooks to enforce commit message format:
```bash
npm install --save-dev husky
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit ${1}'
```
---
## Resources
**Specifications:**
- Conventional Commits: https://www.conventionalcommits.org/
- Git Commit Guidelines: https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project
**Tools:**
- Commitizen: https://github.com/commitizen/cz-cli
- Commitlint: https://commitlint.js.org/
**Further Reading:**
- "How to Write a Git Commit Message": https://chris.beams.io/posts/git-commit/
- Angular Commit Guidelines: https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit

533
references/files-to-exclude.md Normal file
View File

@@ -0,0 +1,533 @@
# Files to Exclude from Pull Requests
A comprehensive reference of files that should NEVER be included in open source pull requests, organized by category.
---
## Personal Development Artifacts
### Session & Notes Files
```
❌ SESSION.md # Session tracking
❌ NOTES.md # Development notes
❌ TODO.md # Personal todo lists
❌ SCRATCH.md # Scratch notes
❌ DEBUGGING.md # Debugging notes
❌ TESTING.md # Testing notes
❌ JOURNAL.md # Development journal
❌ IDEAS.md # Personal ideas
❌ THOUGHTS.md # Random thoughts
❌ WIP.md # Work in progress notes
```
### Planning Documents
```
❌ planning/ # Entire planning directory
❌ IMPLEMENTATION_PHASES.md # Phase-based planning
❌ DATABASE_SCHEMA.md # Database planning (unless adding to project)
❌ ARCHITECTURE.md # Architecture planning (unless adding to project)
❌ API_ENDPOINTS.md # API planning (unless adding to project)
❌ UI_COMPONENTS.md # UI planning (unless adding to project)
❌ PROJECT_SPEC.md # Project specifications
❌ ROADMAP.md # Personal roadmap
❌ MILESTONES.md # Personal milestones
```
### Research & Reference
```
❌ research-logs/ # Research directory
❌ references/ # Personal references (skill-specific)
❌ research-*.md # Research documents
❌ analysis-*.md # Analysis documents
❌ comparison-*.md # Comparison documents
❌ evaluation-*.md # Evaluation documents
```
---
## Screenshots & Visual Assets
### Debug & Development Screenshots
```
❌ screenshots/debug-*.png # Debugging screenshots
❌ screenshots/test-*.png # Testing screenshots
❌ screenshots/scratch-*.png # Scratch screenshots
❌ screenshot-*.png # Ad-hoc screenshots
❌ screen-recording-*.mp4 # Screen recordings
❌ before-after-local.png # Local comparisons
❌ demo-local.* # Local demos
❌ temp-visual.* # Temporary visuals
```
### When Screenshots ARE Okay
```
✅ docs/assets/ui-example.png # Documentation assets
✅ screenshots/feature-demo.png # Demonstrating feature in PR description
✅ docs/images/architecture.png # Architecture diagrams for project docs
```
**Rule of Thumb**: Only include screenshots if they:
1. Demonstrate a feature for the PR description
2. Are part of documentation updates
3. Would be useful to all users/developers
---
## Test Files (Situational)
### Temporary Test Files (NEVER Include)
```
❌ test-manual.js # Manual testing scripts
❌ test-debug.ts # Debugging tests
❌ test-quick.py # Quick validation tests
❌ scratch-test.sh # Scratch test scripts
❌ example-local.json # Local test data
❌ quick-test.* # Quick test files
❌ debug-test.* # Debug test files
❌ temp-test.* # Temporary tests
❌ playground.* # Playground files
❌ experiment.* # Experimental files
```
### Proper Test Files (Include These)
```
✅ tests/feature.test.js # Proper test suite
✅ tests/fixtures/data.json # Required test fixtures
✅ __tests__/component.tsx # Component tests
✅ spec/feature_spec.rb # RSpec tests
✅ test_feature.py # Python tests
```
**Rule**: Only include tests that:
1. Are part of the project's test suite structure
2. Follow project's testing conventions
3. Will be run by CI/other developers
4. Test the specific feature/fix in the PR
---
## Build Artifacts & Dependencies
### Build Output
```
❌ dist/ # Build output
❌ build/ # Build directory
❌ out/ # Output directory
❌ target/ # Rust/Java build directory
❌ bin/ # Binary output (usually)
❌ lib/ # Library output (usually)
❌ *.exe, *.dll, *.so # Compiled binaries
❌ *.o, *.obj # Object files
❌ *.pyc, *.pyo # Python compiled files
❌ __pycache__/ # Python cache
❌ .next/ # Next.js build
❌ .nuxt/ # Nuxt build
❌ .output/ # Nitro build
```
### Dependencies
```
❌ node_modules/ # Node dependencies
❌ vendor/ # Ruby/PHP dependencies
❌ venv/ # Python virtual environment
❌ .venv/ # Python virtual environment
❌ env/ # Environment directory
❌ Cargo.lock # Rust dependencies (situational)
❌ package-lock.json # NPM lock (situational)
❌ yarn.lock # Yarn lock (situational)
❌ pnpm-lock.yaml # PNPM lock (situational)
```
**Lock File Rule**: Only include lock files if:
- Project explicitly requires them (check CONTRIBUTING.md)
- You're adding/updating dependencies
- Project uses lock files (check existing files in repo)
### Cache & Temporary Build Files
```
❌ .cache/ # Cache directory
❌ .tmp/ # Temporary files
❌ .temp/ # Temporary files
❌ tmp/ # Temporary directory
❌ temp/ # Temporary directory
❌ *.cache # Cache files
❌ .eslintcache # ESLint cache
❌ .parcel-cache/ # Parcel cache
❌ .turbo/ # Turborepo cache
```
---
## IDE & Editor Files
### VS Code
```
❌ .vscode/ # VS Code settings (use global gitignore)
❌ *.code-workspace # Workspace files
```
### JetBrains (IntelliJ, WebStorm, etc.)
```
❌ .idea/ # IntelliJ settings
❌ *.iml # Module files
❌ *.ipr # Project files
❌ *.iws # Workspace files
```
### Vim
```
❌ *.swp # Swap files
❌ *.swo # Swap files
❌ *~ # Backup files
❌ .*.sw? # Swap files pattern
```
### Emacs
```
❌ *~ # Backup files
❌ \#*\# # Auto-save files
❌ .\#* # Lock files
```
### Sublime Text
```
❌ *.sublime-project # Project files
❌ *.sublime-workspace # Workspace files
```
**Exception**: If the project provides official IDE configurations (like .vscode/settings.json in the repo), you may update those if needed for the feature.
---
## Operating System Files
### macOS
```
❌ .DS_Store # Finder metadata
❌ .AppleDouble # Resource forks
❌ .LSOverride # Icon metadata
❌ ._* # Resource forks
```
### Windows
```
❌ Thumbs.db # Thumbnail cache
❌ ehthumbs.db # Thumbnail cache
❌ Desktop.ini # Folder settings
❌ $RECYCLE.BIN/ # Recycle bin
```
### Linux
```
❌ .directory # KDE directory settings
❌ .Trash-*/ # Trash directory
```
---
## Secrets & Credentials (CRITICAL!)
### Environment Files
```
❌ .env # Environment variables (NEVER!)
❌ .env.local # Local environment
❌ .env.development # Development environment
❌ .env.production # Production environment (NEVER!)
❌ .env.*.local # Any local env files
❌ config/local.json # Local configuration
❌ config/secrets.json # Secrets configuration
```
### Credentials
```
❌ credentials.json # Credentials file
❌ secrets.json # Secrets file
❌ auth.json # Authentication file
❌ token.txt # Token files
❌ api-keys.json # API keys
❌ service-account.json # Service account credentials
```
### Keys & Certificates
```
❌ *.key # Private keys
❌ *.pem # PEM certificates
❌ *.p12 # PKCS#12 certificates
❌ *.pfx # PFX certificates
❌ id_rsa # SSH private key
❌ id_dsa # SSH private key
❌ *.crt (sometimes) # Certificates
```
### Password & Secret Patterns
Look for these in file contents:
```
❌ password=
❌ api_key=
❌ api-key=
❌ apiKey=
❌ secret=
❌ token=
❌ access_token=
❌ private_key=
```
**CRITICAL**: Even if deleted later, secrets in git history are compromised. Use `git filter-branch` or BFG Repo-Cleaner if secrets are committed.
---
## Logs & Debugging
### Log Files
```
❌ *.log # Log files
❌ logs/ # Logs directory
❌ debug.log # Debug logs
❌ error.log # Error logs
❌ npm-debug.log # NPM debug logs
❌ yarn-debug.log # Yarn debug logs
❌ yarn-error.log # Yarn error logs
❌ lerna-debug.log # Lerna debug logs
```
### Debug Files
```
❌ debug-*.js # Debug scripts
❌ debug-*.py # Debug scripts
❌ trace-*.txt # Trace files
❌ profile-*.json # Profiling output
❌ *.prof # Profiling files
❌ *.trace # Trace files
```
### Crash Dumps
```
❌ core # Core dumps
❌ core.* # Core dumps
❌ *.dmp # Dump files
❌ crash-*.log # Crash logs
```
---
## Database & Data Files
### Database Files (Local Development)
```
❌ *.db # SQLite databases (local)
❌ *.sqlite # SQLite databases (local)
❌ *.sqlite3 # SQLite databases (local)
❌ dump.sql # Database dumps
❌ backup.sql # Database backups
❌ *.mdb # Access databases
```
### Data Files (Local/Personal)
```
❌ data/local/ # Local data directory
❌ data/personal/ # Personal data
❌ data/test-data.json # Test data (unless fixtures)
❌ sample-data-local.json # Local sample data
```
**Exception**: Include database files if:
- They're part of the project's test fixtures
- They're example/seed data for the project
- Project explicitly includes them (check existing repo)
---
## Coverage & Reports
### Test Coverage
```
❌ coverage/ # Coverage reports
❌ .coverage # Coverage data
❌ htmlcov/ # HTML coverage
❌ .nyc_output/ # NYC coverage
❌ lcov.info # LCOV coverage
```
### Reports
```
❌ reports/ # Generated reports
❌ test-results/ # Test results
❌ junit.xml # JUnit reports
❌ cypress/videos/ # Cypress videos
❌ cypress/screenshots/ # Cypress screenshots (unless demonstrating bug)
```
---
## Version Control (Other Than Git)
### SVN
```
❌ .svn/ # SVN metadata
```
### Mercurial
```
❌ .hg/ # Mercurial metadata
❌ .hgignore # Mercurial ignore
```
### CVS
```
❌ CVS/ # CVS metadata
❌ .cvsignore # CVS ignore
```
---
## What SHOULD Be Included
For reference, these ARE okay to include:
### Source Code
```
✅ src/ # Source code
✅ lib/ # Library code (if source, not compiled)
✅ app/ # Application code
✅ components/ # Component files
✅ utils/ # Utility functions
```
### Tests
```
✅ tests/ # Test directory
✅ __tests__/ # Jest tests
✅ spec/ # RSpec tests
✅ test_*.py # Python tests
```
### Documentation
```
✅ README.md # Project readme
✅ CHANGELOG.md # Changelog
✅ CONTRIBUTING.md # Contributing guide
✅ LICENSE # License file
✅ docs/ # Documentation directory
```
### Configuration (Project-level)
```
✅ .gitignore # Git ignore rules
✅ .eslintrc # ESLint config (if updating)
✅ .prettierrc # Prettier config (if updating)
✅ tsconfig.json # TypeScript config (if updating)
✅ package.json # NPM package file (if updating)
✅ Cargo.toml # Rust config (if updating)
✅ pyproject.toml # Python config (if updating)
```
### CI/CD (if part of feature)
```
✅ .github/workflows/ # GitHub Actions
✅ .gitlab-ci.yml # GitLab CI
✅ .travis.yml # Travis CI
✅ Jenkinsfile # Jenkins
```
### Migrations & Schema (if part of feature)
```
✅ migrations/ # Database migrations
✅ schema.sql # Database schema (if adding to project)
✅ seeds/ # Seed data (if part of project)
```
---
## How to Prevent Including These Files
### 1. Project .gitignore
Add patterns that benefit ALL developers:
```gitignore
# Build
dist/
build/
*.pyc
# Dependencies
node_modules/
vendor/
# Logs
*.log
# Secrets
.env
.env.local
*.key
*.pem
```
### 2. Global .gitignore (Recommended)
Add personal/OS-specific patterns:
```bash
# Configure global gitignore
git config --global core.excludesfile ~/.gitignore_global
# Add your patterns
echo ".DS_Store" >> ~/.gitignore_global
echo ".vscode/" >> ~/.gitignore_global
echo ".idea/" >> ~/.gitignore_global
echo "*.swp" >> ~/.gitignore_global
```
### 3. Local Exclusions (.git/info/exclude)
For patterns specific to YOUR workflow only:
```bash
echo "SESSION.md" >> .git/info/exclude
echo "NOTES.md" >> .git/info/exclude
echo "planning/" >> .git/info/exclude
echo "screenshots/debug-*" >> .git/info/exclude
```
**Difference**:
- `.gitignore` → Committed, affects everyone
- `~/.gitignore_global` → Your global settings, affects all your repos
- `.git/info/exclude` → This repo only, not committed
---
## Quick Check Commands
### List all tracked files:
```bash
git ls-files
```
### Check for specific patterns:
```bash
git ls-files | grep -E "SESSION|NOTES|TODO|planning"
```
### Find large files:
```bash
git ls-files | while read file; do
[ -f "$file" ] && stat -f%z "$file" "$file"
done | sort -rn | head -20
```
### Search for secrets in staged files:
```bash
git diff --cached | grep -iE "password|secret|api[_-]?key|token"
```
### Use the pre-PR check script:
```bash
./scripts/pre-pr-check.sh
```
---
## Resources
- **Pre-PR Check Script**: Automated scanning for these patterns
- **Clean Branch Script**: Remove common artifacts safely
- **GitHub's gitignore templates**: https://github.com/github/gitignore
---
**Remember**: When in doubt, DON'T include it. You can always add files later if needed, but removing them from git history is much harder.

351
references/pr-checklist.md Normal file
View 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.

266
references/pr-template.md Normal file
View File

@@ -0,0 +1,266 @@
# Pull Request Template
Use this template when creating pull requests to open source projects. Adapt as needed based on the project's CONTRIBUTING.md guidelines.
---
## Standard PR Template (What/Why/How)
```markdown
## What?
[Brief, clear description of what this PR does - 1-2 sentences]
## Why?
[Explain the reasoning, problem being solved, or business value - 2-3 sentences]
## How?
[Describe the implementation approach and key decisions - bullet points work well]
- Key change 1
- Key change 2
- Key change 3
## Testing
[Step-by-step instructions for reviewers to test the changes]
1. Step 1
2. Step 2
3. Expected result
## Checklist
- [ ] Tests added/updated
- [ ] Documentation updated
- [ ] CI passing
- [ ] Breaking changes documented (if any)
- [ ] Follows project code style
## Related Issues
Closes #[issue number]
Relates to #[issue number]
## Screenshots (if applicable)
[Add screenshots for visual changes, UI updates, or bug fixes]
## Additional Notes
[Any other context, concerns, or questions for reviewers]
```
---
## Example: Feature Addition
```markdown
## What?
Add OAuth2 authentication support for Google and GitHub providers
## Why?
Users have requested social login to reduce friction during signup. This implements Key Result 2 of Q4 OKR1 and addresses multiple user requests from issue #234.
## How?
- Implemented OAuth2 flow using passport.js strategy pattern
- Added provider configuration via environment variables
- Created callback routes for each provider (/auth/google/callback, /auth/github/callback)
- Updated user model to link social accounts with existing email-based accounts
- Added middleware to merge accounts if user already exists
## Testing
1. Set up OAuth apps in Google and GitHub developer consoles
2. Add credentials to `.env` file (see `.env.example` for required variables)
3. Run `npm install` to ensure passport dependencies are installed
4. Start server: `npm start`
5. Navigate to `/login`
6. Click "Login with Google" button
7. Verify OAuth flow redirects correctly
8. Verify user profile data merges correctly with existing account (if applicable)
9. Test GitHub provider following same steps
## Checklist
- [x] Tests added for OAuth flow (see tests/auth/oauth.test.js)
- [x] Documentation updated (see docs/authentication.md)
- [x] CI passing
- [x] No breaking changes
- [x] Follows existing code style
- [x] Environment variables documented in .env.example
## Related Issues
Closes #234
Relates to #156 (social login epic)
## Screenshots
![OAuth Login Buttons](./screenshots/oauth-buttons.png)
*New social login buttons on login page*
## Additional Notes
- Chose passport.js over custom implementation for security and maintenance
- Used strategy pattern to make adding new providers easier in future
- Account merging happens automatically based on email address
- Consider adding rate limiting for OAuth endpoints in future PR
```
---
## Example: Bug Fix
```markdown
## What?
Fix memory leak in worker process shutdown
## Why?
The worker pool wasn't properly cleaning up connections when shutting down gracefully, leading to memory leaks over time. This was causing production issues on long-running instances and reported in #456.
## How?
- Added connection cleanup in worker shutdown handler
- Implemented timeout for graceful shutdown (30s default)
- Added mutex locks to prevent race conditions during cleanup
- Updated tests to verify proper cleanup
## Testing
1. Run load test: `npm run test:load`
2. Monitor memory usage: `npm run monitor:memory`
3. Trigger graceful shutdown: `kill -SIGTERM <pid>`
4. Verify memory is released (check monitor output)
5. Run for 24 hours to verify no gradual memory increase
Manual testing:
- Tested on staging for 48 hours with production load
- Memory usage remained stable at ~120MB
- Previous behavior showed gradual increase to 2GB+ over 24h
## Checklist
- [x] Tests added for shutdown cleanup
- [x] Documentation updated (shutdown behavior in README)
- [x] CI passing
- [x] No breaking changes
- [x] Tested on staging environment
## Related Issues
Fixes #456
## Additional Notes
- Considered force-killing workers after timeout, but went with graceful degradation
- Mutex implementation follows existing pattern in connection-pool.js
- Backward compatible with existing shutdown handlers
```
---
## Example: Refactoring
```markdown
## What?
Refactor authentication middleware to improve testability and reduce duplication
## Why?
The authentication logic was duplicated across 5 different route handlers, making it difficult to test and maintain. This refactoring consolidates the logic into reusable middleware.
## How?
- Extracted auth logic into `middleware/authenticate.js`
- Created composable middleware functions:
- `requireAuth()` - Basic authentication check
- `requireRole(role)` - Role-based access control
- `optionalAuth()` - Sets user if authenticated, continues if not
- Updated all routes to use new middleware
- Maintained backward compatibility with existing behavior
## Testing
1. Run full test suite: `npm test`
2. Verify authentication still works:
- Try accessing protected route without token (should get 401)
- Access with valid token (should succeed)
- Access with invalid token (should get 401)
3. Verify role-based access:
- User role trying admin endpoint (should get 403)
- Admin role trying admin endpoint (should succeed)
All existing tests pass without modification, demonstrating backward compatibility.
## Checklist
- [x] All existing tests pass
- [x] Added tests for new middleware functions
- [x] Documentation updated
- [x] CI passing
- [x] No breaking changes
- [x] Code coverage maintained
## Related Issues
Relates to #301 (technical debt epic)
## Additional Notes
- No changes to API contracts - purely internal refactoring
- Reduces code duplication from ~200 lines to ~50 lines
- Future PRs can add new auth strategies more easily
- All 5 route handlers tested individually to verify behavior unchanged
```
---
## Example: Documentation Update
```markdown
## What?
Update installation instructions for v2.0 and add troubleshooting section
## Why?
Users have reported confusion about new installation requirements in v2.0. Multiple support requests (#567, #589, #601) asking about the same issues.
## How?
- Updated README.md with new installation steps
- Added prerequisites section (Node.js 18+, npm 9+)
- Created troubleshooting guide for common issues
- Added examples for different deployment scenarios
- Fixed typos and outdated links
## Testing
- Followed installation steps on fresh Ubuntu 22.04 VM
- Tested on macOS Ventura
- Verified all links work
- Asked non-technical user to follow guide (successfully completed)
## Checklist
- [x] All links verified working
- [x] Code examples tested
- [x] Markdown formatting validated
- [x] Screenshots updated to v2.0 UI
- [x] Spelling and grammar checked
## Related Issues
Closes #567, #589, #601
## Screenshots
N/A (documentation only)
## Additional Notes
- Kept v1.0 migration guide in separate file (MIGRATION.md)
- Added FAQ section based on common support questions
- Consider adding video walkthrough in future
```
---
## Tips for Writing Good PR Descriptions
### Do:
✅ Be specific and clear
✅ Explain WHY, not just WHAT
✅ Provide testing instructions
✅ Link related issues
✅ Include screenshots for visual changes
✅ Note breaking changes prominently
✅ Keep it concise but complete
### Don't:
❌ Just repeat the commit message
❌ Leave sections empty ("TODO", "TBD")
❌ Assume reviewers know the context
❌ Include implementation details better suited for code comments
❌ Write a novel (keep it scannable)
❌ Skip testing instructions
---
## Project-Specific Variations
Some projects have specific PR template requirements. Check for:
- `.github/PULL_REQUEST_TEMPLATE.md` in the repository
- Instructions in CONTRIBUTING.md
- Examples in recently merged PRs
**Always adapt this template to match project expectations.**

190
scripts/clean-branch.sh Executable file
View File

@@ -0,0 +1,190 @@
#!/bin/bash
# Clean Branch Script
# Safely removes common personal development artifacts before PR submission
# Part of the open-source-contributions skill
set -e
# Colors for output
RED='\033[0;31m'
YELLOW='\033[1;33m'
GREEN='\033[0;32m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
echo -e "${BLUE}====================================${NC}"
echo -e "${BLUE} Clean Branch for PR${NC}"
echo -e "${BLUE}====================================${NC}"
echo ""
# Check if we're in a git repository
if ! git rev-parse --git-dir > /dev/null 2>&1; then
echo -e "${RED}✗ Not in a git repository${NC}"
exit 1
fi
# Interactive mode flag
INTERACTIVE=true
if [ "$1" = "--non-interactive" ] || [ "$1" = "-y" ]; then
INTERACTIVE=false
fi
# Files to potentially remove
PERSONAL_FILES=(
"SESSION.md"
"NOTES.md"
"TODO.md"
"SCRATCH.md"
"DEBUGGING.md"
"TESTING.md"
)
FOUND_FILES=()
echo -e "${BLUE}Scanning for personal development artifacts...${NC}"
echo ""
# Check for personal files
for file in "${PERSONAL_FILES[@]}"; do
if git ls-files --error-unmatch "$file" > /dev/null 2>&1; then
FOUND_FILES+=("$file")
echo -e "${YELLOW} Found: $file${NC}"
fi
done
# Check for planning directory
if git ls-files | grep -q "^planning/"; then
FOUND_FILES+=("planning/")
echo -e "${YELLOW} Found: planning/* directory${NC}"
git ls-files | grep "^planning/" | head -5 | sed 's/^/ - /'
PLANNING_COUNT=$(git ls-files | grep "^planning/" | wc -l)
if [ "$PLANNING_COUNT" -gt 5 ]; then
echo -e "${YELLOW} ... and $((PLANNING_COUNT - 5)) more files${NC}"
fi
fi
# Check for debug screenshots
DEBUG_SCREENSHOTS=$(git ls-files | grep -E "(debug|test|scratch).*\.(png|jpg|jpeg|gif)" || true)
if [ -n "$DEBUG_SCREENSHOTS" ]; then
echo -e "${YELLOW} Found: debug/test screenshots${NC}"
echo "$DEBUG_SCREENSHOTS" | sed 's/^/ - /'
FOUND_FILES+=("screenshots-debug")
fi
# Check for temporary test files
TEMP_TESTS=$(git ls-files | grep -iE "(test-manual|test-debug|quick-test|scratch-test|example-local)" || true)
if [ -n "$TEMP_TESTS" ]; then
echo -e "${YELLOW} Found: temporary test files${NC}"
echo "$TEMP_TESTS" | sed 's/^/ - /'
FOUND_FILES+=("temp-tests")
fi
echo ""
# If nothing found, exit
if [ ${#FOUND_FILES[@]} -eq 0 ]; then
echo -e "${GREEN}✓ No personal artifacts found!${NC}"
echo -e "${GREEN}Your branch is clean.${NC}"
exit 0
fi
# Confirm removal
if [ "$INTERACTIVE" = true ]; then
echo -e "${YELLOW}These files should not be included in your PR.${NC}"
echo -e "${BLUE}Would you like to remove them? (y/n)${NC}"
read -r response
if [[ ! "$response" =~ ^[Yy]$ ]]; then
echo -e "${YELLOW}Cancelled. No files removed.${NC}"
exit 0
fi
fi
echo ""
echo -e "${BLUE}Removing files...${NC}"
REMOVED_COUNT=0
# Remove personal files
for file in "${PERSONAL_FILES[@]}"; do
if git ls-files --error-unmatch "$file" > /dev/null 2>&1; then
git rm --cached "$file" 2>/dev/null || git rm "$file" 2>/dev/null || true
echo -e "${GREEN} ✓ Removed: $file${NC}"
((REMOVED_COUNT++))
fi
done
# Remove planning directory
if git ls-files | grep -q "^planning/"; then
git rm --cached -r "planning/" 2>/dev/null || git rm -r "planning/" 2>/dev/null || true
echo -e "${GREEN} ✓ Removed: planning/* directory${NC}"
((REMOVED_COUNT++))
fi
# Remove debug screenshots (interactive)
if [ -n "$DEBUG_SCREENSHOTS" ]; then
if [ "$INTERACTIVE" = true ]; then
echo ""
echo -e "${YELLOW}Found debug screenshots. Remove these too? (y/n)${NC}"
echo "$DEBUG_SCREENSHOTS" | sed 's/^/ - /'
read -r response
if [[ "$response" =~ ^[Yy]$ ]]; then
echo "$DEBUG_SCREENSHOTS" | while read -r file; do
git rm --cached "$file" 2>/dev/null || git rm "$file" 2>/dev/null || true
echo -e "${GREEN} ✓ Removed: $file${NC}"
done
((REMOVED_COUNT++))
fi
else
echo "$DEBUG_SCREENSHOTS" | while read -r file; do
git rm --cached "$file" 2>/dev/null || git rm "$file" 2>/dev/null || true
done
echo -e "${GREEN} ✓ Removed: debug screenshots${NC}"
((REMOVED_COUNT++))
fi
fi
# Remove temporary test files (interactive)
if [ -n "$TEMP_TESTS" ]; then
if [ "$INTERACTIVE" = true ]; then
echo ""
echo -e "${YELLOW}Found temporary test files. Remove these too? (y/n)${NC}"
echo "$TEMP_TESTS" | sed 's/^/ - /'
read -r response
if [[ "$response" =~ ^[Yy]$ ]]; then
echo "$TEMP_TESTS" | while read -r file; do
git rm --cached "$file" 2>/dev/null || git rm "$file" 2>/dev/null || true
echo -e "${GREEN} ✓ Removed: $file${NC}"
done
((REMOVED_COUNT++))
fi
else
echo "$TEMP_TESTS" | while read -r file; do
git rm --cached "$file" 2>/dev/null || git rm "$file" 2>/dev/null || true
done
echo -e "${GREEN} ✓ Removed: temporary test files${NC}"
((REMOVED_COUNT++))
fi
fi
echo ""
echo -e "${BLUE}====================================${NC}"
if [ $REMOVED_COUNT -gt 0 ]; then
echo -e "${GREEN}✓ Cleaned $REMOVED_COUNT artifact(s)${NC}"
echo ""
echo -e "${BLUE}Next steps:${NC}"
echo -e " 1. Review changes: ${YELLOW}git status${NC}"
echo -e " 2. Commit removal: ${YELLOW}git commit -m 'chore: remove personal development artifacts'${NC}"
echo -e " 3. Re-run check: ${YELLOW}./scripts/pre-pr-check.sh${NC}"
echo -e " 4. Push changes: ${YELLOW}git push${NC}"
else
echo -e "${GREEN}✓ No files removed${NC}"
fi
echo ""
echo -e "${YELLOW}Note:${NC} Files are removed from git tracking but still exist locally."
echo -e "Add them to .git/info/exclude to prevent re-adding:"
echo ""
echo -e "${BLUE}echo 'SESSION.md' >> .git/info/exclude${NC}"
echo -e "${BLUE}echo 'planning/' >> .git/info/exclude${NC}"

249
scripts/pre-pr-check.sh Executable file
View File

@@ -0,0 +1,249 @@
#!/bin/bash
# Pre-PR Check Script
# Scans for common personal development artifacts before PR submission
# Part of the open-source-contributions skill
set -e
# Colors for output
RED='\033[0;31m'
YELLOW='\033[1;33m'
GREEN='\033[0;32m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
echo -e "${BLUE}====================================${NC}"
echo -e "${BLUE} Pre-PR Validation Check${NC}"
echo -e "${BLUE}====================================${NC}"
echo ""
ERRORS=0
WARNINGS=0
# Check if we're in a git repository
if ! git rev-parse --git-dir > /dev/null 2>&1; then
echo -e "${RED}✗ Not in a git repository${NC}"
exit 1
fi
# Get current branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
echo -e "${BLUE}Current branch:${NC} $CURRENT_BRANCH"
echo ""
# Check 1: Personal Development Artifacts
echo -e "${BLUE}[1/8] Checking for personal development artifacts...${NC}"
PERSONAL_FILES=(
"SESSION.md"
"NOTES.md"
"TODO.md"
"SCRATCH.md"
"DEBUGGING.md"
"TESTING.md"
)
for file in "${PERSONAL_FILES[@]}"; do
if git ls-files --error-unmatch "$file" > /dev/null 2>&1; then
echo -e "${RED} ✗ Found: $file (should not be in PR)${NC}"
((ERRORS++))
fi
done
# Check planning directory
if git ls-files | grep -q "^planning/"; then
echo -e "${RED} ✗ Found: planning/* directory (should not be in PR)${NC}"
git ls-files | grep "^planning/" | head -5 | sed 's/^/ - /'
((ERRORS++))
fi
if [ $ERRORS -eq 0 ]; then
echo -e "${GREEN} ✓ No personal development artifacts found${NC}"
fi
echo ""
# Check 2: Screenshots and Visual Assets
echo -e "${BLUE}[2/8] Checking for debug screenshots...${NC}"
DEBUG_SCREENSHOTS=$(git ls-files | grep -E "screenshot.*\.(png|jpg|jpeg|gif|mp4|mov)" || true)
if [ -n "$DEBUG_SCREENSHOTS" ]; then
echo -e "${YELLOW} ⚠ Found screenshots:${NC}"
echo "$DEBUG_SCREENSHOTS" | sed 's/^/ - /'
echo -e "${YELLOW} → Ensure these are needed for PR description (demonstrating feature)${NC}"
echo -e "${YELLOW} → Remove if they're just debugging artifacts${NC}"
((WARNINGS++))
else
echo -e "${GREEN} ✓ No screenshot files found${NC}"
fi
echo ""
# Check 3: Temporary Test Files
echo -e "${BLUE}[3/8] Checking for temporary test files...${NC}"
TEMP_TEST_PATTERNS=(
"test-manual"
"test-debug"
"quick-test"
"scratch-test"
"example-local"
"debug-"
"temp-"
"tmp-"
)
TEMP_TESTS_FOUND=0
for pattern in "${TEMP_TEST_PATTERNS[@]}"; do
MATCHES=$(git ls-files | grep -i "$pattern" || true)
if [ -n "$MATCHES" ]; then
echo -e "${RED} ✗ Found temporary test files matching '$pattern':${NC}"
echo "$MATCHES" | sed 's/^/ - /'
((ERRORS++))
TEMP_TESTS_FOUND=1
fi
done
if [ $TEMP_TESTS_FOUND -eq 0 ]; then
echo -e "${GREEN} ✓ No temporary test files found${NC}"
fi
echo ""
# Check 4: Large Files
echo -e "${BLUE}[4/8] Checking for large files (>1MB)...${NC}"
LARGE_FILES=$(git ls-files | while read file; do
if [ -f "$file" ]; then
size=$(stat -c%s "$file" 2>/dev/null || stat -f%z "$file" 2>/dev/null)
if [ "$size" -gt 1048576 ]; then
echo "$file ($(numfmt --to=iec-i --suffix=B $size 2>/dev/null || echo "$((size / 1024))KB"))"
fi
fi
done)
if [ -n "$LARGE_FILES" ]; then
echo -e "${YELLOW} ⚠ Found large files:${NC}"
echo "$LARGE_FILES" | sed 's/^/ - /'
echo -e "${YELLOW} → Ensure these are necessary for the PR${NC}"
((WARNINGS++))
else
echo -e "${GREEN} ✓ No large files found${NC}"
fi
echo ""
# Check 5: Potential Secrets
echo -e "${BLUE}[5/8] Checking for potential secrets...${NC}"
SECRET_PATTERNS=(
"\.env$"
"\.env\.local$"
"credentials\.json$"
"\.key$"
"\.pem$"
"secret"
"password"
"api[_-]?key"
"access[_-]?token"
)
SECRETS_FOUND=0
for pattern in "${SECRET_PATTERNS[@]}"; do
MATCHES=$(git ls-files | grep -iE "$pattern" || true)
if [ -n "$MATCHES" ]; then
echo -e "${RED} ✗ Found potential secrets matching '$pattern':${NC}"
echo "$MATCHES" | sed 's/^/ - /'
((ERRORS++))
SECRETS_FOUND=1
fi
done
if [ $SECRETS_FOUND -eq 0 ]; then
echo -e "${GREEN} ✓ No potential secrets found in file names${NC}"
fi
echo ""
# Check 6: PR Size
echo -e "${BLUE}[6/8] Checking PR size...${NC}"
# Get default branch (usually main or master)
DEFAULT_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d' ' -f5)
if [ -z "$DEFAULT_BRANCH" ]; then
DEFAULT_BRANCH="main"
fi
# Count lines changed
if git rev-parse --verify "origin/$DEFAULT_BRANCH" > /dev/null 2>&1; then
LINES_CHANGED=$(git diff --shortstat "origin/$DEFAULT_BRANCH" | grep -oE '[0-9]+ insertion|[0-9]+ deletion' | grep -oE '[0-9]+' | paste -sd+ | bc || echo "0")
FILES_CHANGED=$(git diff --name-only "origin/$DEFAULT_BRANCH" | wc -l)
echo -e "${BLUE} Lines changed:${NC} $LINES_CHANGED"
echo -e "${BLUE} Files changed:${NC} $FILES_CHANGED"
if [ "$LINES_CHANGED" -lt 50 ]; then
echo -e "${GREEN} ✓ Small PR (< 50 lines) - Ideal!${NC}"
elif [ "$LINES_CHANGED" -lt 200 ]; then
echo -e "${GREEN} ✓ Good PR size (< 200 lines)${NC}"
elif [ "$LINES_CHANGED" -lt 400 ]; then
echo -e "${YELLOW} ⚠ Large PR (< 400 lines) - Consider splitting if possible${NC}"
((WARNINGS++))
else
echo -e "${RED} ✗ Very large PR (>= 400 lines) - Strongly consider splitting${NC}"
((ERRORS++))
fi
else
echo -e "${YELLOW} ⚠ Cannot compare with origin/$DEFAULT_BRANCH${NC}"
((WARNINGS++))
fi
echo ""
# Check 7: Uncommitted Changes
echo -e "${BLUE}[7/8] Checking for uncommitted changes...${NC}"
if ! git diff-index --quiet HEAD --; then
echo -e "${YELLOW} ⚠ You have uncommitted changes${NC}"
git status --short | sed 's/^/ /'
echo -e "${YELLOW} → Commit or stash these before creating PR${NC}"
((WARNINGS++))
else
echo -e "${GREEN} ✓ No uncommitted changes${NC}"
fi
echo ""
# Check 8: Branch Name
echo -e "${BLUE}[8/8] Checking branch name...${NC}"
if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
echo -e "${RED} ✗ You're on $CURRENT_BRANCH branch!${NC}"
echo -e "${RED} → Never create PRs from main/master${NC}"
echo -e "${RED} → Create a feature branch instead${NC}"
((ERRORS++))
else
echo -e "${GREEN} ✓ On feature branch: $CURRENT_BRANCH${NC}"
fi
echo ""
# Summary
echo -e "${BLUE}====================================${NC}"
echo -e "${BLUE} Summary${NC}"
echo -e "${BLUE}====================================${NC}"
if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then
echo -e "${GREEN}✓ All checks passed!${NC}"
echo -e "${GREEN}Your branch is ready for PR submission.${NC}"
exit 0
elif [ $ERRORS -eq 0 ]; then
echo -e "${YELLOW}⚠ $WARNINGS warning(s) found${NC}"
echo -e "${YELLOW}Review warnings above and address if needed.${NC}"
exit 0
else
echo -e "${RED}✗ $ERRORS error(s) found${NC}"
if [ $WARNINGS -gt 0 ]; then
echo -e "${YELLOW}⚠ $WARNINGS warning(s) found${NC}"
fi
echo -e "${RED}Fix errors above before submitting PR.${NC}"
echo ""
echo -e "${BLUE}Next steps:${NC}"
echo -e " 1. Remove personal artifacts: ${YELLOW}git rm --cached <file>${NC}"
echo -e " 2. Clean branch: ${YELLOW}./scripts/clean-branch.sh${NC}"
echo -e " 3. Re-run this check: ${YELLOW}./scripts/pre-pr-check.sh${NC}"
exit 1
fi