From 580282baa1641df35ab8c00c33e906d74c0a206a Mon Sep 17 00:00:00 2001 From: ajaysi Date: Wed, 24 Sep 2025 15:49:53 +0530 Subject: [PATCH] feat: Enhance GitHub community profile with ALwrity-specific improvements - Improve CONTRIBUTING.md with detailed setup instructions and ALwrity-specific guidelines - Enhance SUPPORT.md with comprehensive troubleshooting for AI services and GSC integration - Update SECURITY.md with ALwrity-specific security features and considerations - Add issue template configuration and question form for better issue management - Enhance PR template with ALwrity-specific checklist items - Add comprehensive .github/README.md explaining all community health files These improvements provide better contributor experience and project visibility. --- .github/CONTRIBUTING.md | 83 ++++++++++++++++++++--------- .github/ISSUE_TEMPLATE/config.yml | 11 ++++ .github/ISSUE_TEMPLATE/question.yml | 56 +++++++++++++++++++ .github/README.md | 61 +++++++++++++++++++++ .github/SECURITY.md | 14 +++-- .github/SUPPORT.md | 36 ++++++++----- .github/pull_request_template.md | 14 +++++ 7 files changed, 234 insertions(+), 41 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/question.yml create mode 100644 .github/README.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9a43e304..1a5d698a 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -24,37 +24,61 @@ Thank you for your interest in contributing to ALwrity! ๐Ÿš€ We welcome contribu ## ๐Ÿ› ๏ธ Development Setup ### Prerequisites -- Python 3.10+ -- Node.js 18+ -- Git +- **Python 3.10+** (Backend: FastAPI, SQLAlchemy, AI integrations) +- **Node.js 18+** (Frontend: React, TypeScript, Material-UI) +- **Git** (Version control) +- **API Keys** (Gemini, OpenAI, Anthropic, etc.) -### Backend Setup +### Quick Start ```bash +# Clone the repository +git clone https://github.com/AJaySi/ALwrity.git +cd ALwrity + +# Backend setup cd backend pip install -r requirements.txt +cp env_template.txt .env # Configure your API keys python start_alwrity_backend.py -``` -### Frontend Setup -```bash +# Frontend setup (in a new terminal) cd frontend npm install +cp env_template.txt .env # Configure your environment npm start ``` +### Environment Configuration +1. **Backend**: Copy `backend/env_template.txt` to `backend/.env` +2. **Frontend**: Copy `frontend/env_template.txt` to `frontend/.env` +3. **API Keys**: Add your AI service API keys to the respective `.env` files + ## ๐Ÿ“ Coding Standards ### Python (Backend) -- Follow PEP 8 style guidelines -- Use type hints where possible -- Add docstrings for functions and classes -- Use meaningful variable and function names +- **Style**: Follow PEP 8 guidelines, use Black formatter +- **Type Hints**: Use type hints for all function parameters and return values +- **Documentation**: Add comprehensive docstrings using Google style +- **Error Handling**: Use proper exception handling with meaningful error messages +- **Logging**: Use structured logging with appropriate levels +- **API Design**: Follow RESTful principles, use FastAPI best practices +- **Database**: Use SQLAlchemy ORM, implement proper migrations ### TypeScript/React (Frontend) -- Use TypeScript for type safety -- Follow React best practices -- Use functional components with hooks -- Implement proper error handling +- **TypeScript**: Strict mode enabled, no `any` types +- **Components**: Functional components with hooks, proper prop typing +- **State Management**: Use React hooks, consider context for global state +- **Styling**: Material-UI components, consistent theming +- **Error Boundaries**: Implement error boundaries for better UX +- **Performance**: Use React.memo, useMemo, useCallback where appropriate +- **Testing**: Jest + React Testing Library for unit tests + +### ALwrity-Specific Guidelines +- **AI Integration**: Always handle API rate limits and errors gracefully +- **Content Generation**: Implement proper validation and sanitization +- **SEO Features**: Follow SEO best practices in generated content +- **User Experience**: Maintain consistent UI/UX across all features +- **Security**: Validate all inputs, implement proper authentication ## ๐Ÿงช Testing @@ -120,17 +144,28 @@ We use the following labels to categorize issues: ## ๐ŸŽฏ Areas for Contribution ### High Priority -- Bug fixes and performance improvements -- Documentation improvements -- Test coverage expansion -- UI/UX enhancements +- **Bug Fixes**: Critical issues affecting core functionality +- **Performance**: API response times, database optimization +- **Documentation**: API docs, user guides, setup instructions +- **Test Coverage**: Unit tests, integration tests, E2E tests +- **Security**: Vulnerability fixes, security improvements ### Feature Areas -- AI content generation improvements -- SEO analysis enhancements -- Social media integration -- Analytics and reporting -- User experience improvements +- **AI Content Generation**: Blog posts, social media content, SEO optimization +- **SEO Dashboard**: Google Search Console integration, analytics +- **Social Media**: LinkedIn, Facebook, Instagram content creation +- **Content Planning**: Calendar management, content strategy +- **User Experience**: Onboarding flow, dashboard improvements +- **Analytics**: Usage tracking, performance metrics +- **Integrations**: Third-party API integrations, webhooks + +### Good First Issues +Look for issues labeled with `good first issue` - these are perfect for newcomers: +- Documentation improvements +- UI/UX enhancements +- Test additions +- Bug fixes with clear reproduction steps +- Feature requests with detailed specifications ## ๐Ÿ“ž Getting Help diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..60f3e2ef --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: GitHub Community Support + url: https://github.com/AJaySi/ALwrity/discussions + about: Please ask and answer questions here. + - name: ALwrity Documentation + url: https://github.com/AJaySi/ALwrity/wiki + about: Check our documentation for setup guides and tutorials. + - name: Security Vulnerability + url: https://github.com/AJaySi/ALwrity/security/advisories/new + about: Report security vulnerabilities privately. diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 00000000..e1a4bb32 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,56 @@ +name: Question +description: Ask a question about ALwrity +title: "[QUESTION] " +labels: ["question", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for your question! Please provide as much detail as possible to help us help you. + + - type: textarea + id: question + attributes: + label: What's your question? + description: Please describe your question in detail + placeholder: What would you like to know about ALwrity? + validations: + required: true + + - type: textarea + id: context + attributes: + label: Additional context + description: Any additional context, screenshots, or information that might help + placeholder: Add any relevant context here... + + - type: dropdown + id: component + attributes: + label: Which component/feature is this about? + description: Select the most relevant component + options: + - Blog Writer + - SEO Dashboard + - Content Planning + - Facebook Writer + - LinkedIn Writer + - Onboarding + - Authentication + - API + - Installation/Setup + - Other + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Priority + description: How urgent is this question? + options: + - Low (general question) + - Medium (affecting workflow) + - High (blocking progress) + validations: + required: true diff --git a/.github/README.md b/.github/README.md new file mode 100644 index 00000000..29e33b4d --- /dev/null +++ b/.github/README.md @@ -0,0 +1,61 @@ +# ALwrity Community Health Files + +This directory contains community health files that help maintain a welcoming and productive environment for contributors to ALwrity. + +## ๐Ÿ“ Files Overview + +### Core Community Files +- **`CONTRIBUTING.md`** - Guidelines for contributing to ALwrity +- **`CODE_OF_CONDUCT.md`** - Community standards and behavior expectations +- **`SECURITY.md`** - Security policy and vulnerability reporting +- **`SUPPORT.md`** - Help resources and troubleshooting guides +- **`FUNDING.yml`** - Funding and sponsorship information + +### Issue Templates (`ISSUE_TEMPLATE/`) +- **`bug_report.md`** - Template for reporting bugs +- **`feature_request.md`** - Template for requesting new features +- **`question.yml`** - Form for asking questions +- **`config.yml`** - Issue template configuration + +### Pull Request Template +- **`pull_request_template.md`** - Template for pull requests + +## ๐ŸŽฏ Purpose + +These files help: +- **Improve Project Visibility** - Better GitHub community profile score +- **Enhance Contributor Experience** - Clear guidelines and expectations +- **Streamline Issue Management** - Structured templates for better organization +- **Maintain Quality** - Consistent PR reviews and code standards +- **Build Community** - Welcoming environment for all contributors + +## ๐Ÿ“Š Community Profile Status + +With these files, ALwrity should achieve: +- โœ… **README** - Comprehensive project documentation +- โœ… **Contributing** - Clear contribution guidelines +- โœ… **Code of Conduct** - Community standards +- โœ… **License** - MIT License (in root directory) +- โœ… **Issue Templates** - Structured issue reporting +- โœ… **Pull Request Template** - Consistent PR format +- โœ… **Security Policy** - Vulnerability reporting process +- โœ… **Support** - Help resources and documentation + +## ๐Ÿ”„ Maintenance + +These files should be updated as the project evolves: +- Review and update contribution guidelines quarterly +- Update security policy when new features are added +- Refresh issue templates based on common questions +- Update support resources as new features are released + +## ๐Ÿ“ž Questions? + +If you have questions about these community health files: +- Open an [issue](https://github.com/AJaySi/ALwrity/issues) +- Start a [discussion](https://github.com/AJaySi/ALwrity/discussions) +- Check the [main README](../README.md) for project overview + +--- + +**Thank you for contributing to ALwrity!** ๐Ÿš€ diff --git a/.github/SECURITY.md b/.github/SECURITY.md index 96054846..aa69e7b3 100644 --- a/.github/SECURITY.md +++ b/.github/SECURITY.md @@ -61,14 +61,18 @@ Send an email to: [security@alwrity.com](mailto:security@alwrity.com) ALwrity implements the following security measures: -- **Authentication**: Secure user authentication with JWT tokens -- **Authorization**: Role-based access control -- **Input Validation**: Comprehensive input sanitization -- **API Security**: Rate limiting and request validation +- **Authentication**: Secure user authentication with JWT tokens and Clerk integration +- **Authorization**: Role-based access control and subscription-based access +- **Input Validation**: Comprehensive input sanitization for all user inputs +- **API Security**: Rate limiting, request validation, and API key management - **Data Encryption**: Sensitive data encryption at rest and in transit - **CORS Protection**: Proper cross-origin resource sharing configuration -- **Security Headers**: Implementation of security headers +- **Security Headers**: Implementation of security headers and CSP policies - **Dependency Scanning**: Regular dependency vulnerability scanning +- **AI Service Security**: Secure API key management for AI services +- **Content Sanitization**: Proper sanitization of AI-generated content +- **Database Security**: SQL injection prevention with SQLAlchemy ORM +- **File Upload Security**: Secure file handling and validation ## ๐Ÿšซ Out of Scope diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md index a23dd04e..ed78ed6f 100644 --- a/.github/SUPPORT.md +++ b/.github/SUPPORT.md @@ -9,6 +9,8 @@ We're here to help you get the most out of ALwrity! Here are the best ways to ge - **[API Documentation](https://github.com/AJaySi/ALwrity/wiki/API-Documentation)** - Complete API reference - **[Setup Guide](https://github.com/AJaySi/ALwrity/wiki/Setup-Guide)** - Installation and configuration - **[User Guide](https://github.com/AJaySi/ALwrity/wiki/User-Guide)** - How to use ALwrity features +- **[GSC Integration Guide](GSC_INTEGRATION_README.md)** - Google Search Console setup +- **[Alpha Subscription Guide](backend/ALPHA_SUBSCRIPTION_IMPLEMENTATION_PLAN.md)** - Subscription system ### ๐Ÿ’ฌ Community Support - **[GitHub Discussions](https://github.com/AJaySi/ALwrity/discussions)** - Ask questions and share ideas @@ -68,22 +70,32 @@ npm start ## ๐Ÿ”ง Troubleshooting ### Performance Issues -- Check system resources (CPU, RAM) -- Review database query performance -- Monitor API rate limits -- Clear browser cache and cookies +- **System Resources**: Check CPU, RAM usage during content generation +- **Database**: Review query performance, check for slow queries +- **API Rate Limits**: Monitor AI service rate limits (Gemini, OpenAI, etc.) +- **Browser**: Clear cache, cookies, and local storage +- **Network**: Check internet connectivity and API endpoint accessibility ### Authentication Problems -- Verify API keys are correct -- Check token expiration -- Clear browser storage -- Review authentication logs +- **API Keys**: Verify all AI service API keys are correct and active +- **Environment Variables**: Check `.env` files are properly configured +- **Token Expiration**: Refresh authentication tokens if expired +- **Browser Storage**: Clear browser storage and try again +- **CORS Issues**: Check backend CORS configuration ### Content Generation Issues -- Verify AI service API keys -- Check internet connectivity -- Review content generation logs -- Ensure sufficient API credits +- **AI Service Keys**: Verify Gemini, OpenAI, Anthropic API keys +- **Rate Limits**: Check if you've exceeded API rate limits +- **Content Quality**: Review prompt engineering and content validation +- **Error Logs**: Check backend logs for detailed error messages +- **API Credits**: Ensure sufficient credits for AI services + +### ALwrity-Specific Issues +- **Onboarding**: Check if all required steps are completed +- **SEO Analysis**: Verify Google Search Console integration +- **Subscription Limits**: Check if you've exceeded usage limits +- **Database**: Ensure database is properly initialized +- **File Permissions**: Check file permissions for uploads and cache ## ๐Ÿ“ž Contact Information diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index c1eb4faf..3624daad 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -45,6 +45,10 @@ Which component or feature is affected? - [ ] Authentication - [ ] API - [ ] Database +- [ ] GSC Integration +- [ ] Subscription System +- [ ] Monitoring/Billing +- [ ] Documentation - [ ] Other: _______________ ## ๐Ÿ“‹ Checklist @@ -57,6 +61,16 @@ Which component or feature is affected? - [ ] New and existing unit tests pass locally with my changes - [ ] Any dependent changes have been merged and published +### ALwrity-Specific Checklist +- [ ] API endpoints follow RESTful conventions +- [ ] AI service integrations handle rate limits and errors gracefully +- [ ] Content generation includes proper validation and sanitization +- [ ] Database migrations are included if schema changes are made +- [ ] Environment variables are documented in env_template.txt +- [ ] Security considerations have been addressed +- [ ] Performance impact has been considered +- [ ] User experience is consistent with existing features + ## ๐Ÿ” Code Quality - [ ] Code is properly formatted - [ ] No console.log statements left in production code