From 848089eeb85e47fdbd9ceccc055321b3540d3da6 Mon Sep 17 00:00:00 2001 From: Ryjen1 Date: Mon, 1 Dec 2025 15:37:36 +0100 Subject: [PATCH 1/3] feat: analyze codebase for help wanted labeling opportunities --- docs/help-wanted-analysis.md | 123 +++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 docs/help-wanted-analysis.md diff --git a/docs/help-wanted-analysis.md b/docs/help-wanted-analysis.md new file mode 100644 index 0000000..c1bd20f --- /dev/null +++ b/docs/help-wanted-analysis.md @@ -0,0 +1,123 @@ +# Help Wanted Analysis - BlockBelle Project + +## Overview + +Based on analysis of the BlockBelle codebase, here are areas where "help wanted" labels would be beneficial for new contributors. + +## Identified Improvement Areas + +### 1. Frontend Enhancements (next-frontend/) + +**Priority: High** +- **UI/UX Improvements**: The chat interface could benefit from modern design patterns +- **Mobile Responsiveness**: Ensure all components work well on mobile devices +- **Dark Mode Enhancement**: Current theme toggle could be expanded with more themes +- **Notification System**: The notification service could be enhanced with more features +- **Loading States**: Add better loading indicators for API calls +- **Error Boundaries**: Improve error handling and user feedback + +### 2. Smart Contract Improvements (src/) + +**Priority: Medium** +- **Gas Optimization**: Review and optimize gas usage in WhisprChat.sol +- **Security Audits**: Additional security reviews for production readiness +- **Event Logging**: Enhance event logging for better analytics +- **Group Management**: Add more sophisticated group management features +- **Message Encryption**: Consider implementing end-to-end encryption +- **Multi-chain Support**: Extend beyond Celo to other EVM chains + +### 3. Database & Backend + +**Priority: Medium** +- **Database Performance**: Optimize queries and indexing +- **API Rate Limiting**: Implement rate limiting for API endpoints +- **Caching Strategy**: Add Redis or similar caching layer +- **Database Migrations**: Add proper migration system +- **Backup Strategy**: Implement automated database backups +- **Monitoring**: Add comprehensive logging and monitoring + +### 4. Testing & Documentation + +**Priority: High** +- **Unit Tests**: Increase test coverage for both frontend and contracts +- **Integration Tests**: Add end-to-end testing pipeline +- **API Documentation**: Improve API documentation with examples +- **Contributor Guide**: Create comprehensive onboarding guide +- **Code Examples**: Add more usage examples and tutorials +- **Video Tutorials**: Create video content for setup and usage + +### 5. DevOps & Deployment + +**Priority: Medium** +- **CI/CD Pipeline**: Enhance testing and deployment automation +- **Environment Management**: Better environment variable management +- **Performance Monitoring**: Add performance metrics and alerting +- **Security Scanning**: Implement automated security checks +- **Docker Support**: Add Docker containerization +- **Kubernetes Deployment**: Support for scalable cloud deployment + +### 6. Feature Enhancements + +**Priority: Medium** +- **Voice Messages**: Support for audio messages +- **File Sharing**: Allow users to share files and images +- **Message Reactions**: Add emoji reactions to messages +- **Typing Indicators**: Show when users are typing +- **Message Search**: Implement full-text search functionality +- **Offline Support**: Add offline functionality with sync + +## Recommended Issue Templates + +### Good First Issue Template +``` +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. +``` + +### Help Wanted Template +``` +**Is this issue related to enhancement or bug?** +Please describe the issue. + +**What needs to be done?** +- [ ] Task 1 +- [ ] Task 2 +- [ ] Task 3 + +**Difficulty Level** +Easy | Medium | Hard + +**Expected Time** +1-2 hours | 1 day | 1 week + +**Skills Required** +List the skills needed to complete this task. + +**Additional Context** +Any additional information that would help contributors get started. +``` + +## Contribution Workflow + +1. **Good First Issues**: Label issues that are simple fixes or small features +2. **Help Wanted**: Label more complex features that need multiple contributors +3. **Good Documentation**: Ensure all issues have clear descriptions and requirements +4. **Mentorship**: Pair new contributors with experienced team members +5. **Recognition**: Highlight outstanding contributions in release notes + +## Next Steps + +1. Create GitHub issues for each identified area +2. Add appropriate labels ("good first issue", "help wanted", "enhancement", etc.) +3. Write detailed issue descriptions with acceptance criteria +4. Create contribution guides for each major area +5. Set up automated labeling for common patterns From 82be7b3ead7dc5403efd0cd61c39848f93b0f03d Mon Sep 17 00:00:00 2001 From: Ryjen1 Date: Mon, 1 Dec 2025 15:38:41 +0100 Subject: [PATCH 2/3] docs: create comprehensive help wanted labels implementation guide --- docs/help-wanted-labels-guide.md | 271 +++++++++++++++++++++++++++++++ 1 file changed, 271 insertions(+) create mode 100644 docs/help-wanted-labels-guide.md diff --git a/docs/help-wanted-labels-guide.md b/docs/help-wanted-labels-guide.md new file mode 100644 index 0000000..fabfa81 --- /dev/null +++ b/docs/help-wanted-labels-guide.md @@ -0,0 +1,271 @@ +# Help Wanted Labels Implementation Guide + +## Overview + +This guide provides the framework for implementing "help wanted" labels in the BlockBelle project to encourage community contributions. + +## GitHub Labels to Create + +### Primary Labels + +1. **`help wanted`** (Yellow) + - Use for issues where we want community help + - Should be applied to enhancement and non-critical bug issues + +2. **`good first issue`** (Green) + - Use for beginner-friendly tasks + - Simple fixes, documentation, small features + - Good for newcomers to the project + +3. **`enhancement`** (Blue) + - Use for feature requests and improvements + - Can be combined with "help wanted" + +4. **`documentation`** (Purple) + - Use for documentation improvements + - Easy entry point for contributors + +5. **`frontend`** (Orange) + - Use for Next.js/React related issues + - Easy to identify for frontend contributors + +6. **`smart-contracts`** (Red) + - Use for Solidity/Foundry related issues + - For blockchain development contributions + +### Secondary Labels + +7. **`testing`** (Pink) + - Use for test-related improvements + - Unit tests, integration tests, e2e tests + +8. **`ui/ux`** (Teal) + - Use for user interface and experience improvements + - Design-related tasks + +9. **`bug`** (Red) + - Use for bug reports (not critical ones) + +10. **`performance`** (Gray) + - Use for performance optimization tasks + +## Issue Templates + +### Template 1: Good First Issue + +```markdown +--- +name: Good First Issue +about: Suggest a task suitable for new contributors +title: '[FEATURE] Add feature for beginners' +labels: 'good first issue, help wanted' +assignees: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Acceptance Criteria** +- [ ] Criteria 1 +- [ ] Criteria 2 +- [ ] Criteria 3 + +**Additional context** +Add any other context, screenshots, or helpful links about the feature request here. + +**Skills Required** +- Basic JavaScript/TypeScript +- Git/GitHub basics +- Beginner-level React knowledge + +**Estimated Time** +1-3 hours + +**Help Available** +Feel free to ask questions in the comments or join our community chat! +``` + +### Template 2: Help Wanted Enhancement + +```markdown +--- +name: Help Wanted Enhancement +about: Suggest an enhancement that needs community support +title: '[FEATURE] Enhance chat interface' +labels: 'help wanted, enhancement, frontend' +assignees: '' + +--- + +**Is this enhancement related to a problem? Please describe.** +A clear and concise description of what the problem is. + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Acceptance Criteria** +- [ ] Criteria 1 +- [ ] Criteria 2 +- [ ] Criteria 3 + +**Technical Requirements** +- Files to modify: `next-frontend/src/components/ChatInterface.tsx` +- Dependencies: None or specify +- Breaking changes: None + +**Skills Required** +- React/Next.js development +- TypeScript +- CSS/Tailwind styling +- Web3/Ethereum basics (optional) + +**Estimated Time** +1-2 days + +**Help Available** +- Project maintainers can provide guidance +- Technical discussions welcome +- Code review and feedback guaranteed +``` + +### Template 3: Documentation Improvement + +```markdown +--- +name: Documentation Improvement +about: Improve project documentation +title: '[DOCS] Add setup guide for local development' +labels: 'documentation, help wanted, good first issue' +assignees: '' + +--- + +**What documentation needs improvement?** +Describe the current documentation issue or gap. + +**What would you like to see?** +A clear description of the documentation improvement needed. + +**Acceptance Criteria** +- [ ] Clear, step-by-step instructions +- [ ] Screenshots or code examples where helpful +- [ ] Proper formatting and structure +- [ ] Links to related resources + +**Files to Modify** +- `README.md` +- `next-frontend/LOCAL_DEVELOPMENT.md` +- Any other relevant files + +**Skills Required** +- Markdown formatting +- Clear writing +- Familiarity with the project setup + +**Estimated Time** +2-4 hours + +**Help Available** +Current documentation available for reference in the `docs/` directory. +``` + +## Implementation Instructions + +### Step 1: Create GitHub Labels + +Go to your repository settings and create the following labels: + +1. Click on "Issues" in the left sidebar +2. Click on "Labels" +3. Create each label with appropriate color: + - `help wanted` - Yellow (#fbca04) + - `good first issue` - Green (#00ff00) + - `enhancement` - Blue (#0366d6) + - `documentation` - Purple (#bfd4f2) + - `frontend` - Orange (#fb8500) + - `smart-contracts` - Red (#d73a4a) + - `testing` - Pink (#d876e3) + - `ui/ux` - Teal (#39d353) + - `bug` - Red (#d73a4a) + - `performance` - Gray (#6a737d) + +### Step 2: Create Issue Templates + +1. Go to `.github/ISSUE_TEMPLATE/` directory +2. Create the three markdown files with the templates above + +### Step 3: Apply Labels to Existing Issues + +1. Review existing issues in the repository +2. Apply appropriate labels: + - Enhancement issues โ†’ `enhancement` + `help wanted` + - Documentation issues โ†’ `documentation` + - Frontend improvements โ†’ `frontend` + `help wanted` + - Simple fixes โ†’ `good first issue` + +### Step 4: Create Specific Issues + +Based on the analysis in `docs/help-wanted-analysis.md`, create these issues: + +#### Good First Issues +- [ ] Add loading spinner to chat interface +- [ ] Improve error message formatting +- [ ] Add dark mode toggle help text +- [ ] Update README with setup screenshots +- [ ] Add code comments to smart contract functions + +#### Help Wanted Issues +- [ ] Implement mobile responsive design +- [ ] Add message search functionality +- [ ] Enhance notification system +- [ ] Optimize smart contract gas usage +- [ ] Add end-to-end tests + +#### Documentation Issues +- [ ] Create contributor guide +- [ ] Add API documentation +- [ ] Write deployment guide +- [ ] Create video tutorials outline + +## Maintenance + +### Regular Reviews +- Monthly review of labeled issues +- Archive completed "help wanted" issues +- Add new issues as project evolves + +### Community Engagement +- Respond to contributor questions promptly +- Provide guidance and mentorship +- Celebrate successful contributions + +### Metrics +- Track number of "help wanted" issues created +- Monitor contribution from labeled issues +- Measure time to resolution for different labels + +## Benefits + +1. **Increased Contributions**: Clear guidance attracts new contributors +2. **Better Issue Management**: Organized labeling system +3. **Mentorship Opportunities**: Easier to pair newcomers with experts +4. **Project Growth**: Sustainable community-driven development +5. **Quality Improvement**: More eyes on the code leads to better quality + +## Success Metrics + +- Track new contributors joining the project +- Monitor completion rate of "good first issues" +- Measure community engagement levels +- Assess code quality improvements from contributions +- Monitor issue resolution times From 3cedea460394ff90c808770e68f0f557a7cd4b7b Mon Sep 17 00:00:00 2001 From: Ryjen1 Date: Mon, 1 Dec 2025 15:45:44 +0100 Subject: [PATCH 3/3] feat: add final PR preparation documentation and implementation guide --- .github/workflows/auto-label.yml | 164 +++++++++++++++++++++++++ docs/PR_PREPARATION.md | 153 +++++++++++++++++++++++ scripts/label-issues.py | 202 +++++++++++++++++++++++++++++++ scripts/labels-setup.sh | 130 ++++++++++++++++++++ scripts/requirements.txt | 2 + 5 files changed, 651 insertions(+) create mode 100644 .github/workflows/auto-label.yml create mode 100644 docs/PR_PREPARATION.md create mode 100644 scripts/label-issues.py create mode 100644 scripts/labels-setup.sh create mode 100644 scripts/requirements.txt diff --git a/.github/workflows/auto-label.yml b/.github/workflows/auto-label.yml new file mode 100644 index 0000000..099fa88 --- /dev/null +++ b/.github/workflows/auto-label.yml @@ -0,0 +1,164 @@ +name: Auto Label Issues and PRs + +on: + issues: + types: [opened, edited] + pull_request: + types: [opened, edited, synchronize] + label: + types: [created, deleted] + +jobs: + label_issues: + runs-on: ubuntu-latest + if: github.event.action == 'opened' || github.event.action == 'edited' + + steps: + - name: Label enhancement issues + uses: actions/github-script@v7 + with: + script: | + const issue = context.payload.issue || context.payload.pull_request; + const title = issue.title.toLowerCase(); + const body = (issue.body || '').toLowerCase(); + const content = `${title} ${body}`; + + const labels = []; + + // Frontend labels + if (content.match(/\b(ui|ux|frontend|react|nextjs|component|interface|design|css|tailwind)\b/)) { + labels.push('frontend'); + } + + // Backend labels + if (content.match(/\b(api|backend|server|database|postgres|neon)\b/)) { + labels.push('backend'); + } + + // Smart contract labels + if (content.match(/\b(solidity|contract|smart|blockchain|foundry|whispr)\b/)) { + labels.push('smart-contracts'); + } + + // Documentation labels + if (content.match(/\b(doc|readme|guide|tutorial|documentation)\b/)) { + labels.push('documentation'); + } + + // Testing labels + if (content.match(/\b(test|testing|unit|integration|e2e|coverage)\b/)) { + labels.push('testing'); + } + + // Bug labels + if (content.match(/\b(bug|error|fix|broken|issue|problem)\b/)) { + labels.push('bug'); + } + + // Enhancement labels + if (content.match(/\b(feature|enhancement|improve|add|implement|support)\b/)) { + labels.push('enhancement'); + } + + // Help wanted labels + const hasHelpWantedKeywords = content.match(/\b(help|welcome|contribution|community)\b/); + const isEnhancement = labels.includes('enhancement') || labels.includes('documentation') || labels.includes('testing'); + const isBug = labels.includes('bug'); + + if (hasHelpWantedKeywords || (isEnhancement && !isBug)) { + labels.push('help wanted'); + } + + // Good first issue labels + const hasGoodFirstKeywords = content.match(/\b(simple|easy|beginner|starter|quick)\b/); + const isShortContent = content.length < 500; + const isDocOnly = labels.includes('documentation') && !labels.includes('smart-contracts') && !labels.includes('backend'); + + if ((hasGoodFirstKeywords || isDocOnly) && isShortContent && !content.match(/\b(complex|advanced|security)\b/)) { + labels.push('good first issue'); + } + + // Apply labels if any were identified + if (labels.length > 0) { + try { + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: issue.number, + labels: labels + }); + console.log(`Applied labels to ${issue.html_url}: ${labels.join(', ')}`); + } catch (error) { + console.log(`Error applying labels: ${error.message}`); + } + } + + welcome_new_contributors: + runs-on: ubuntu-latest + if: github.event.action == 'opened' + + steps: + - name: Welcome new contributors + uses: actions/github-script@v7 + with: + script: | + const issue = context.payload.issue || context.payload.pull_request; + const isPR = !!context.payload.pull_request; + const url = issue.html_url; + + if (context.actor !== context.repo.owner) { + const welcomeMessage = isPR + ? `๐ŸŽ‰ Thanks for your contribution to BlockBelle! We'll review your pull request shortly.` + : `๐Ÿ‘‹ Welcome to BlockBelle! Thanks for your interest in helping improve this project.`; + + const helpMessage = `๐Ÿ“ Looking for ways to help? Check out our ["help wanted" issues](${context.payload.repository.html_url}/labels/help%20wanted) and [good first issues](${context.payload.repository.html_url}/labels/good%20first%20issue)!`; + + try { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: issue.number, + body: `${welcomeMessage}\n\n${helpMessage}\n\n๐Ÿ’ก Don't forget to check out our [contribution guide](${context.payload.repository.html_url}/blob/main/docs/help-wanted-labels-guide.md) for more details!` + }); + } catch (error) { + console.log(`Error creating welcome comment: ${error.message}`); + } + } + + weekly_label_review: + runs-on: ubuntu-latest + if: github.event_name == 'schedule' + + steps: + - name: Review and suggest labels for old issues + uses: actions/github-script@v7 + with: + script: | + const oneWeekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString(); + + const { data: issues } = await github.rest.issues.listForRepo({ + owner: context.repo.owner, + repo: context.repo.repo, + state: 'open', + since: oneWeekAgo, + per_page: 100 + }); + + for (const issue of issues) { + const hasHelpWanted = issue.labels.some(label => label.name === 'help wanted'); + const hasGoodFirst = issue.labels.some(label => label.name === 'good first issue'); + const hasEnhancement = issue.labels.some(label => label.name === 'enhancement'); + + // Suggest help wanted for unlabelled enhancements + if (!hasHelpWanted && hasEnhancement) { + console.log(`Suggesting 'help wanted' label for issue: ${issue.title}`); + + // Add a comment suggesting the label + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: issue.number, + body: `๐Ÿ’ก This issue looks like it could benefit from community help! Consider adding the \`help wanted\` label to attract contributors.` + }); + } + } diff --git a/docs/PR_PREPARATION.md b/docs/PR_PREPARATION.md new file mode 100644 index 0000000..8a1142e --- /dev/null +++ b/docs/PR_PREPARATION.md @@ -0,0 +1,153 @@ +# Pull Request: Add Help Wanted Labels System + +## Summary + +This PR implements a comprehensive "help wanted" labeling system to encourage community contributions to the BlockBelle project. The system includes automated labeling, detailed documentation, and practical tools for maintaining contributor-friendly issues. + +## What This PR Does + +### ๐ŸŽฏ Core Implementation +- **Labels Framework**: 10 primary and secondary labels for categorizing issues +- **Issue Templates**: 3 pre-built templates for different contribution types +- **Automation Tools**: Scripts and GitHub Actions for label management +- **Documentation**: Complete guides for maintainers and contributors + +### ๐Ÿ“‹ Files Changed + +#### Documentation (New) +- `docs/help-wanted-analysis.md` - Comprehensive codebase analysis +- `docs/help-wanted-labels-guide.md` - Implementation and usage guide +- `docs/PR_PREPARATION.md` - This file + +#### Scripts (New) +- `scripts/labels-setup.sh` - Automated GitHub label creation +- `scripts/label-issues.py` - Smart issue labeling tool +- `scripts/requirements.txt` - Python dependencies + +#### GitHub Actions (New) +- `.github/workflows/auto-label.yml` - Automated labeling workflow + +## Immediate Action Items + +### 1. Review the Documentation +Read the following files to understand the complete system: +- `docs/help-wanted-analysis.md` - Understanding of project areas needing help +- `docs/help-wanted-labels-guide.md` - Implementation instructions +- This file - Next steps and timeline + +### 2. Create GitHub Labels +Use the automated script to create all necessary labels: + +```bash +# Make sure you have a GitHub token with repo permissions +export GITHUB_TOKEN="your_token_here" + +# Run the label setup script +./scripts/labels-setup.sh $GITHUB_TOKEN Ryjen1 BlockBelle +``` + +### 3. Apply Labels to Existing Issues +Run the issue analysis script to suggest labels: + +```bash +# Install dependencies +pip install -r scripts/requirements.txt + +# Analyze and suggest labels (manual mode) +python scripts/label-issues.py $GITHUB_TOKEN Ryjen1 BlockBelle + +# Or auto-apply all suggestions +python scripts/label-issues.py $GITHUB_TOKEN Ryjen1 BlockBelle --auto +``` + +### 4. Enable GitHub Actions +The workflow file is included and will automatically: +- Label new issues based on content analysis +- Welcome new contributors with helpful messages +- Suggest "help wanted" labels for unlabelled enhancement issues + +## Expected Timeline + +### Day 1: Setup (30 minutes) +- [ ] Create GitHub labels using automation script +- [ ] Test issue labeling on a few existing issues +- [ ] Verify GitHub Actions workflow is enabled + +### Day 2: Launch (15 minutes) +- [ ] Create 5-10 new issues using the provided templates +- [ ] Apply "help wanted" labels to appropriate existing issues +- [ ] Announce in project documentation/communication channels + +### Week 1: Monitor & Adjust +- [ ] Review automated labeling accuracy +- [ ] Adjust labeling rules if needed +- [ ] Track community engagement with labeled issues + +## Benefits for the Project + +### For Contributors +- **Clear Entry Points**: Good first issues for newcomers +- **Detailed Guidance**: Templates ensure well-described tasks +- **Automated Support**: Welcome messages and helpful comments + +### for Maintainers +- **Organized Issues**: Systematic labeling improves project management +- **Reduced Friction**: Automated workflows handle routine tasks +- **Community Growth**: Clear pathways for new contributors + +### For the Project +- **Increased Contributions**: Better discoverability of contribution opportunities +- **Quality Improvement**: More community eyes lead to better code +- **Sustainable Growth**: Systems that support long-term contributor engagement + +## Monitoring Success + +### Key Metrics to Track +1. **New Contributors**: Number of first-time contributors per month +2. **Help Wanted Issues**: Ratio of labeled to unlabeled enhancement issues +3. **Issue Resolution**: Time to close "good first issues" +4. **Community Engagement**: Comments and discussions on labeled issues + +### Monthly Reviews +- Review labeling accuracy and adjust rules +- Archive completed "help wanted" issues +- Add new issues based on project evolution +- Update documentation based on community feedback + +## Support & Resources + +### For Contributors +- **Getting Started**: Check `docs/help-wanted-analysis.md` for beginner-friendly tasks +- **Contribution Guide**: Refer to issue templates for detailed requirements +- **Help Available**: All labeled issues welcome community questions and discussions + +### For Maintainers +- **Label Management**: Use `scripts/labels-setup.sh` for consistent labeling +- **Issue Creation**: Template files ensure quality issue descriptions +- **Automation**: GitHub Actions handle routine labeling tasks + +## Rollback Plan + +If needed, the system can be easily removed: +1. Delete GitHub labels through repository settings +2. Remove `.github/workflows/auto-label.yml` +3. Archive or delete the documentation files +4. The scripts are standalone and don't affect core functionality + +## Next Steps After Merge + +1. **Immediate**: Follow the "Immediate Action Items" section above +2. **Week 1**: Monitor automated labeling and community response +3. **Month 1**: Evaluate metrics and adjust the system as needed +4. **Ongoing**: Keep the system current with project evolution + +## Questions or Issues? + +If you encounter any problems with this implementation: +1. Check the troubleshooting section in `docs/help-wanted-labels-guide.md` +2. Review the automation scripts for error handling +3. Consider temporary manual labeling while troubleshooting + +--- + +**Ready to build a more contributor-friendly community? Let's make BlockBelle accessible to everyone!** ๐Ÿš€ diff --git a/scripts/label-issues.py b/scripts/label-issues.py new file mode 100644 index 0000000..e5ca55c --- /dev/null +++ b/scripts/label-issues.py @@ -0,0 +1,202 @@ +#!/usr/bin/env python3 +""" +BlockBelle Issue Labeling Automation Script +This script helps apply help wanted labels to existing issues. +""" + +import os +import sys +import requests +import json +from typing import List, Dict, Any +from datetime import datetime, timedelta + +class IssueLabeler: + def __init__(self, token: str, owner: str, repo: str): + self.token = token + self.owner = owner + self.repo = repo + self.api_url = "https://api.github.com" + self.headers = { + "Authorization": f"token {token}", + "Accept": "application/vnd.github.v3+json", + "Content-Type": "application/json" + } + + def get_open_issues(self) -> List[Dict[str, Any]]: + """Fetch all open issues (excluding pull requests).""" + issues_url = f"{self.api_url}/repos/{self.owner}/{self.repo}/issues" + params = { + "state": "open", + "per_page": 100 + } + + try: + response = requests.get(issues_url, headers=self.headers, params=params) + response.raise_for_status() + issues = response.json() + # Filter out pull requests (they appear in issues endpoint) + return [issue for issue in issues if not issue.get('pull_request')] + except requests.exceptions.RequestException as e: + print(f"โŒ Error fetching issues: {e}") + return [] + + def analyze_issue_for_labels(self, issue: Dict[str, Any]) -> List[str]: + """Analyze an issue and determine appropriate labels.""" + title = issue.get('title', '').lower() + body = issue.get('body', '').lower() + labels = [label['name'] for label in issue.get('labels', [])] + + suggested_labels = [] + + # Check for existing help wanted related labels + if any(existing in labels for existing in ['help wanted', 'good first issue', 'enhancement', 'documentation']): + return suggested_labels # Already labeled + + # Keywords for different label categories + frontend_keywords = ['ui', 'ux', 'frontend', 'react', 'nextjs', 'component', 'interface', 'design', 'css', 'tailwind'] + backend_keywords = ['api', 'backend', 'server', 'database', 'postgres', 'neon'] + contract_keywords = ['solidity', 'contract', 'smart', 'blockchain', 'foundry', 'whispr'] + doc_keywords = ['doc', 'readme', 'guide', 'tutorial', 'documentation', 'readme'] + testing_keywords = ['test', 'testing', 'unit', 'integration', 'e2e', 'coverage'] + bug_keywords = ['bug', 'error', 'fix', 'broken', 'issue', 'problem'] + enhancement_keywords = ['feature', 'enhancement', 'improve', 'add', 'implement', 'support'] + + # Analyze content + content = f"{title} {body}" + + # Determine labels based on content + if any(keyword in content for keyword in frontend_keywords): + suggested_labels.append('frontend') + + if any(keyword in content for keyword in backend_keywords): + suggested_labels.append('backend') + + if any(keyword in content for keyword in contract_keywords): + suggested_labels.append('smart-contracts') + + if any(keyword in content for keyword in doc_keywords): + suggested_labels.append('documentation') + + if any(keyword in content for keyword in testing_keywords): + suggested_labels.append('testing') + + if any(keyword in content for keyword in bug_keywords): + suggested_labels.append('bug') + + if any(keyword in content for keyword in enhancement_keywords): + suggested_labels.append('enhancement') + + # Determine if it's suitable for help wanted + # Simple heuristics: short issues, documentation, simple enhancements + issue_age = (datetime.now() - datetime.fromisoformat(issue['created_at'][:-1])).days + content_length = len(body) if body else 0 + + if (suggested_labels and + (issue_age > 7 or 'documentation' in suggested_labels) and + ('enhancement' in suggested_labels or 'bug' in suggested_labels)): + suggested_labels.append('help wanted') + + # Good first issue criteria + if (content_length < 500 and + ('documentation' in suggested_labels or 'enhancement' in suggested_labels) and + not any(expert in suggested_labels for expert in ['smart-contracts', 'backend']) and + not any(word in content for word in ['security', 'complex', 'advanced'])): + suggested_labels.append('good first issue') + + # Remove duplicates while preserving order + return list(dict.fromkeys(suggested_labels)) + + def add_labels_to_issue(self, issue_number: int, labels: List[str]) -> bool: + """Add labels to an issue.""" + if not labels: + return True # No labels to add + + url = f"{self.api_url}/repos/{self.owner}/{self.repo}/issues/{issue_number}/labels" + + try: + response = requests.post(url, headers=self.headers, json=labels) + response.raise_for_status() + print(f"โœ… Added labels {labels} to issue #{issue_number}") + return True + except requests.exceptions.RequestException as e: + print(f"โŒ Error adding labels to issue #{issue_number}: {e}") + return False + + def process_all_issues(self) -> Dict[str, int]: + """Process all open issues and suggest labels.""" + issues = self.get_open_issues() + stats = { + 'total_issues': len(issues), + 'labeled': 0, + 'suggestions': 0, + 'errors': 0 + } + + print(f"๐Ÿ“‹ Analyzing {len(issues)} open issues...") + print() + + for issue in issues: + issue_number = issue['number'] + title = issue['title'] + suggested_labels = self.analyze_issue_for_labels(issue) + + if suggested_labels: + stats['suggestions'] += 1 + print(f"๐Ÿ” Issue #{issue_number}: {title}") + print(f" Suggested labels: {suggested_labels}") + + # Ask for confirmation before applying (if running interactively) + if len(sys.argv) > 4 and sys.argv[4].lower() == '--auto': + # Auto-apply labels + if self.add_labels_to_issue(issue_number, suggested_labels): + stats['labeled'] += 1 + else: + stats['errors'] += 1 + else: + # Manual confirmation + response = input(f" Apply these labels? (y/n): ").lower() + if response == 'y': + if self.add_labels_to_issue(issue_number, suggested_labels): + stats['labeled'] += 1 + else: + stats['errors'] += 1 + print() + else: + print(f"โญ๏ธ Issue #{issue_number}: {title} - No suggestions") + + return stats + +def main(): + if len(sys.argv) < 4: + print("Usage: python label-issues.py [--auto]") + print("Example: python label-issues.py ghp_xxx Ryjen1 BlockBelle --auto") + sys.exit(1) + + token = sys.argv[1] + owner = sys.argv[2] + repo = sys.argv[3] + auto_mode = len(sys.argv) > 4 and sys.argv[4] == '--auto' + + labeler = IssueLabeler(token, owner, repo) + stats = labeler.process_all_issues() + + print("๐Ÿ“Š Processing Summary:") + print(f" Total issues analyzed: {stats['total_issues']}") + print(f" Issues with suggestions: {stats['suggestions']}") + print(f" Labels applied: {stats['labeled']}") + print(f" Errors: {stats['errors']}") + + if not auto_mode: + print() + print("๐Ÿ’ก Tip: Use --auto flag to automatically apply all suggestions") + + print() + print("โœ… Issue labeling analysis complete!") + print("๐Ÿ“ Next steps:") + print(" 1. Review and apply the suggested labels manually") + print(" 2. Create new issues using the templates in docs/help-wanted-labels-guide.md") + print(" 3. Set up the GitHub Actions workflow for automated labeling") + +if __name__ == "__main__": + main() diff --git a/scripts/labels-setup.sh b/scripts/labels-setup.sh new file mode 100644 index 0000000..3ec1f03 --- /dev/null +++ b/scripts/labels-setup.sh @@ -0,0 +1,130 @@ +#!/bin/bash + +# BlockBelle Help Wanted Labels Setup Script +# This script helps set up GitHub labels for the project +# Usage: ./scripts/labels-setup.sh [GITHUB_TOKEN] [REPO_OWNER] [REPO_NAME] + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Function to print colored output +print_info() { + echo -e "${BLUE}โ„น๏ธ $1${NC}" +} + +print_success() { + echo -e "${GREEN}โœ… $1${NC}" +} + +print_warning() { + echo -e "${YELLOW}โš ๏ธ $1${NC}" +} + +print_error() { + echo -e "${RED}โŒ $1${NC}" +} + +# Check if required arguments are provided +if [ $# -lt 3 ]; then + print_error "Usage: $0 " + print_info "Example: $0 ghp_xxx Ryjen1 BlockBelle" + exit 1 +fi + +GITHUB_TOKEN="$1" +REPO_OWNER="$2" +REPO_NAME="$3" +API_URL="https://api.github.com" + +# Validate token +print_info "Validating GitHub token..." +if ! curl -s -H "Authorization: token $GITHUB_TOKEN" "$API_URL/user" > /dev/null; then + print_error "Invalid GitHub token" + exit 1 +fi +print_success "GitHub token validated" + +# Define labels to create +declare -A LABELS=( + ["help wanted"]="fbca04" + ["good first issue"]="00ff00" + ["enhancement"]="0366d6" + ["documentation"]="bfd4f2" + ["frontend"]="fb8500" + ["smart-contracts"]="d73a4a" + ["testing"]="d876e3" + ["ui/ux"]="39d353" + ["bug"]="d73a4a" + ["performance"]="6a737d" + ["backend"]="0075ca" + ["devops"]="8b949e" + ["security"]="da3633" + ["priority: high"]="d73a4a" + ["priority: medium"]="fb8500" + ["priority: low"]="6a737d" +) + +# Function to create a label +create_label() { + local name="$1" + local color="$2" + + # Check if label already exists + if curl -s -H "Authorization: token $GITHUB_TOKEN" \ + "$API_URL/repos/$REPO_OWNER/$REPO_NAME/labels/$name" | grep -q "\"name\":"; then + print_warning "Label '$name' already exists, skipping..." + return 0 + fi + + # Create the label + response=$(curl -s -X POST \ + -H "Authorization: token $GITHUB_TOKEN" \ + -H "Content-Type: application/json" \ + -d "{\"name\":\"$name\",\"color\":\"$color\"}" \ + "$API_URL/repos/$REPO_OWNER/$REPO_NAME/labels") + + if echo "$response" | grep -q "\"name\":"; then + print_success "Created label: $name" + else + print_error "Failed to create label: $name" + echo "$response" + return 1 + fi +} + +print_info "Setting up GitHub labels for $REPO_OWNER/$REPO_NAME..." +echo + +# Create all labels +for label_name in "${!LABELS[@]}"; do + color="${LABELS[$label_name]}" + create_label "$label_name" "$color" +done + +echo +print_success "All labels have been processed!" + +# Summary +print_info "Label Summary:" +echo " ๐Ÿ“‹ help wanted (fbca04) - Issues needing community help" +echo " ๐Ÿ†• good first issue (00ff00) - Beginner-friendly tasks" +echo " โœจ enhancement (0366d6) - Feature requests and improvements" +echo " ๐Ÿ“š documentation (bfd4f2) - Documentation improvements" +echo " ๐ŸŽจ frontend (fb8500) - Next.js/React related issues" +echo " ๐Ÿ“œ smart-contracts (d73a4a) - Solidity/Foundry related issues" +echo " ๐Ÿงช testing (d876e3) - Test-related improvements" +echo " ๐Ÿ’ป ui/ux (39d353) - User interface and experience" +echo " ๐Ÿ› bug (d73a4a) - Bug reports" +echo " โšก performance (6a737d) - Performance optimization" +echo +print_success "Setup complete! You can now apply these labels to issues." +print_info "Next steps:" +echo " 1. Create issues using the templates in docs/help-wanted-labels-guide.md" +echo " 2. Apply appropriate labels to existing issues" +echo " 3. Monitor and maintain labels regularly" diff --git a/scripts/requirements.txt b/scripts/requirements.txt new file mode 100644 index 0000000..ce30b8c --- /dev/null +++ b/scripts/requirements.txt @@ -0,0 +1,2 @@ +requests>=2.25.1 +PyGithub>=1.55