Base code
This commit is contained in:
Kunthawat Greethong
410
docs-site/docs/user-journeys/developers/contributing.md
Normal file
410
docs-site/docs/user-journeys/developers/contributing.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# Contributing - Developers
|
||||
|
||||
This guide covers how to contribute to the ALwrity project, including development setup, coding standards, and the contribution process.
|
||||
|
||||
## 🎯 What You'll Accomplish
|
||||
|
||||
By the end of this guide, you'll have:
|
||||
- ✅ Set up your development environment
|
||||
- ✅ Understood the contribution process
|
||||
- ✅ Learned coding standards and best practices
|
||||
- ✅ Started contributing to the ALwrity project
|
||||
|
||||
## ⏱️ Time Required: 1-2 hours
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
### Development Setup
|
||||
|
||||
#### Prerequisites
|
||||
Before contributing to ALwrity, ensure you have:
|
||||
|
||||
**Required Software**
|
||||
- **Python 3.10+**: For backend development
|
||||
- **Node.js 18+**: For frontend development
|
||||
- **Git**: For version control
|
||||
- **Docker**: For containerized development
|
||||
- **API Keys**: Gemini, OpenAI, or other AI service keys
|
||||
|
||||
#### Fork and Clone
|
||||
1. **Fork the Repository** - Fork ALwrity on GitHub
|
||||
2. **Clone Your Fork** - Clone your fork locally
|
||||
3. **Add Upstream** - Add the main repository as upstream
|
||||
4. **Create Branch** - Create a feature branch for your changes
|
||||
|
||||
```bash
|
||||
# Fork the repository on GitHub, then:
|
||||
git clone https://github.com/YOUR_USERNAME/ALwrity.git
|
||||
cd ALwrity
|
||||
git remote add upstream https://github.com/AJaySi/ALwrity.git
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
|
||||
#### Backend Setup
|
||||
Set up the backend development environment:
|
||||
|
||||
**Install Dependencies**
|
||||
```bash
|
||||
cd backend
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
**Environment Configuration**
|
||||
```bash
|
||||
# Copy environment template
|
||||
cp env_template.txt .env
|
||||
|
||||
# Configure your API keys
|
||||
GEMINI_API_KEY=your_gemini_api_key
|
||||
OPENAI_API_KEY=your_openai_api_key
|
||||
DATABASE_URL=sqlite:///./alwrity.db
|
||||
```
|
||||
|
||||
**Run Backend**
|
||||
```bash
|
||||
python start_alwrity_backend.py
|
||||
```
|
||||
|
||||
#### Frontend Setup
|
||||
Set up the frontend development environment:
|
||||
|
||||
**Install Dependencies**
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
**Environment Configuration**
|
||||
```bash
|
||||
# Copy environment template
|
||||
cp env_template.txt .env
|
||||
|
||||
# Configure your environment
|
||||
REACT_APP_API_URL=http://localhost:8000
|
||||
REACT_APP_COPILOT_API_KEY=your_copilot_api_key
|
||||
```
|
||||
|
||||
**Run Frontend**
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
## 📊 Contribution Process
|
||||
|
||||
### Issue Management
|
||||
Before starting work, check for existing issues:
|
||||
|
||||
**Finding Issues**
|
||||
- **Good First Issues**: Look for issues labeled "good first issue"
|
||||
- **Bug Reports**: Check for bug reports that need fixing
|
||||
- **Feature Requests**: Review feature requests for implementation
|
||||
- **Documentation**: Find documentation that needs improvement
|
||||
|
||||
**Creating Issues**
|
||||
- **Bug Reports**: Provide detailed bug reports with steps to reproduce
|
||||
- **Feature Requests**: Describe the feature and its benefits
|
||||
- **Documentation**: Identify areas that need better documentation
|
||||
- **Questions**: Ask questions about implementation or architecture
|
||||
|
||||
### Pull Request Process
|
||||
Follow the pull request process:
|
||||
|
||||
**Before Submitting**
|
||||
1. **Create Issue** - Create an issue for your feature or bug fix
|
||||
2. **Assign Issue** - Assign the issue to yourself
|
||||
3. **Create Branch** - Create a feature branch from main
|
||||
4. **Make Changes** - Implement your changes
|
||||
5. **Test Changes** - Test your changes thoroughly
|
||||
6. **Update Documentation** - Update relevant documentation
|
||||
|
||||
**Pull Request Guidelines**
|
||||
- **Clear Title** - Use a clear, descriptive title
|
||||
- **Detailed Description** - Describe what your PR does and why
|
||||
- **Link Issues** - Link to related issues
|
||||
- **Screenshots** - Include screenshots for UI changes
|
||||
- **Testing** - Describe how you tested your changes
|
||||
|
||||
**Review Process**
|
||||
- **Code Review** - Address reviewer feedback
|
||||
- **Testing** - Ensure all tests pass
|
||||
- **Documentation** - Update documentation as needed
|
||||
- **Merge** - Merge after approval
|
||||
|
||||
## 🎯 Coding Standards
|
||||
|
||||
### Python Backend Standards
|
||||
Follow Python coding standards:
|
||||
|
||||
**Code Style**
|
||||
- **PEP 8**: Follow PEP 8 style guidelines
|
||||
- **Type Hints**: Use type hints for function parameters and return values
|
||||
- **Docstrings**: Write comprehensive docstrings for functions and classes
|
||||
- **Error Handling**: Implement proper error handling
|
||||
|
||||
**Example Code**
|
||||
```python
|
||||
from typing import List, Optional
|
||||
from fastapi import HTTPException
|
||||
|
||||
def generate_blog_content(
|
||||
topic: str,
|
||||
keywords: List[str],
|
||||
target_audience: Optional[str] = None
|
||||
) -> dict:
|
||||
"""
|
||||
Generate blog content using AI.
|
||||
|
||||
Args:
|
||||
topic: The topic for the blog post
|
||||
keywords: List of keywords to include
|
||||
target_audience: Target audience for the content
|
||||
|
||||
Returns:
|
||||
Dictionary containing generated content and metadata
|
||||
|
||||
Raises:
|
||||
HTTPException: If content generation fails
|
||||
"""
|
||||
try:
|
||||
# Implementation here
|
||||
pass
|
||||
except Exception as e:
|
||||
raise HTTPException(status_code=500, detail=str(e))
|
||||
```
|
||||
|
||||
### TypeScript Frontend Standards
|
||||
Follow TypeScript coding standards:
|
||||
|
||||
**Code Style**
|
||||
- **ESLint**: Use ESLint for code linting
|
||||
- **Prettier**: Use Prettier for code formatting
|
||||
- **TypeScript**: Use strict TypeScript configuration
|
||||
- **React Best Practices**: Follow React best practices
|
||||
|
||||
**Example Code**
|
||||
```typescript
|
||||
interface BlogContentProps {
|
||||
topic: string;
|
||||
keywords: string[];
|
||||
targetAudience?: string;
|
||||
}
|
||||
|
||||
const BlogContent: React.FC<BlogContentProps> = ({
|
||||
topic,
|
||||
keywords,
|
||||
targetAudience
|
||||
}) => {
|
||||
const [content, setContent] = useState<string>('');
|
||||
const [loading, setLoading] = useState<boolean>(false);
|
||||
|
||||
const generateContent = async (): Promise<void> => {
|
||||
setLoading(true);
|
||||
try {
|
||||
// Implementation here
|
||||
} catch (error) {
|
||||
console.error('Error generating content:', error);
|
||||
} finally {
|
||||
setLoading(false);
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<div>
|
||||
{/* Component JSX */}
|
||||
</div>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
### Testing Standards
|
||||
Write comprehensive tests:
|
||||
|
||||
**Backend Testing**
|
||||
- **Unit Tests**: Test individual functions and methods
|
||||
- **Integration Tests**: Test API endpoints and database interactions
|
||||
- **Test Coverage**: Maintain high test coverage
|
||||
- **Test Data**: Use appropriate test data and fixtures
|
||||
|
||||
**Frontend Testing**
|
||||
- **Component Tests**: Test React components
|
||||
- **Integration Tests**: Test component interactions
|
||||
- **E2E Tests**: Test complete user workflows
|
||||
- **Accessibility Tests**: Test accessibility compliance
|
||||
|
||||
## 🚀 Development Workflow
|
||||
|
||||
### Git Workflow
|
||||
Follow the Git workflow:
|
||||
|
||||
**Branch Naming**
|
||||
- **Feature Branches**: `feature/description`
|
||||
- **Bug Fix Branches**: `bugfix/description`
|
||||
- **Hotfix Branches**: `hotfix/description`
|
||||
- **Documentation Branches**: `docs/description`
|
||||
|
||||
**Commit Messages**
|
||||
- **Format**: `type(scope): description`
|
||||
- **Types**: feat, fix, docs, style, refactor, test, chore
|
||||
- **Examples**:
|
||||
- `feat(api): add blog content generation endpoint`
|
||||
- `fix(ui): resolve button alignment issue`
|
||||
- `docs(readme): update installation instructions`
|
||||
|
||||
**Pull Request Process**
|
||||
1. **Create Branch** - Create feature branch from main
|
||||
2. **Make Changes** - Implement your changes
|
||||
3. **Test Changes** - Run tests and ensure they pass
|
||||
4. **Commit Changes** - Commit with descriptive messages
|
||||
5. **Push Branch** - Push branch to your fork
|
||||
6. **Create PR** - Create pull request to main repository
|
||||
7. **Address Feedback** - Address reviewer feedback
|
||||
8. **Merge** - Merge after approval
|
||||
|
||||
### Code Review Process
|
||||
Participate in code reviews:
|
||||
|
||||
**As a Reviewer**
|
||||
- **Check Code Quality** - Review code for quality and standards
|
||||
- **Test Functionality** - Test the functionality of changes
|
||||
- **Provide Feedback** - Give constructive feedback
|
||||
- **Approve Changes** - Approve when ready
|
||||
|
||||
**As an Author**
|
||||
- **Respond to Feedback** - Address reviewer feedback promptly
|
||||
- **Ask Questions** - Ask questions if feedback is unclear
|
||||
- **Make Changes** - Implement requested changes
|
||||
- **Test Changes** - Test changes after addressing feedback
|
||||
|
||||
## 📊 Project Structure
|
||||
|
||||
### Backend Structure
|
||||
Understand the backend project structure:
|
||||
|
||||
**Key Directories**
|
||||
- **`api/`**: API endpoint definitions
|
||||
- **`models/`**: Database models and schemas
|
||||
- **`services/`**: Business logic and service layer
|
||||
- **`middleware/`**: Custom middleware and authentication
|
||||
- **`routers/`**: API route definitions
|
||||
- **`scripts/`**: Utility scripts and database migrations
|
||||
|
||||
**Key Files**
|
||||
- **`app.py`**: Main FastAPI application
|
||||
- **`requirements.txt`**: Python dependencies
|
||||
- **`start_alwrity_backend.py`**: Application startup script
|
||||
|
||||
### Frontend Structure
|
||||
Understand the frontend project structure:
|
||||
|
||||
**Key Directories**
|
||||
- **`src/components/`**: React components
|
||||
- **`src/pages/`**: Page components
|
||||
- **`src/services/`**: API service functions
|
||||
- **`src/utils/`**: Utility functions
|
||||
- **`src/types/`**: TypeScript type definitions
|
||||
|
||||
**Key Files**
|
||||
- **`package.json`**: Node.js dependencies and scripts
|
||||
- **`tsconfig.json`**: TypeScript configuration
|
||||
- **`src/App.tsx`**: Main React application component
|
||||
|
||||
## 🎯 Areas for Contribution
|
||||
|
||||
### High Priority Areas
|
||||
Focus on high-priority contribution areas:
|
||||
|
||||
**Bug Fixes**
|
||||
- **Critical Bugs**: Fix bugs that affect core functionality
|
||||
- **Performance Issues**: Address performance problems
|
||||
- **Security Issues**: Fix security vulnerabilities
|
||||
- **UI/UX Issues**: Improve user interface and experience
|
||||
|
||||
**Feature Development**
|
||||
- **New AI Integrations**: Add support for new AI services
|
||||
- **Content Types**: Add new content generation types
|
||||
- **Platform Integrations**: Add integrations with new platforms
|
||||
- **Analytics**: Improve analytics and reporting features
|
||||
|
||||
### Documentation
|
||||
Contribute to documentation:
|
||||
|
||||
**User Documentation**
|
||||
- **User Guides**: Improve user guides and tutorials
|
||||
- **API Documentation**: Enhance API documentation
|
||||
- **Installation Guides**: Improve installation instructions
|
||||
- **Troubleshooting**: Add troubleshooting guides
|
||||
|
||||
**Developer Documentation**
|
||||
- **Code Comments**: Add inline code comments
|
||||
- **Architecture Docs**: Document system architecture
|
||||
- **Development Guides**: Improve development setup guides
|
||||
- **Contributing Guide**: Enhance this contributing guide
|
||||
|
||||
### Testing
|
||||
Improve test coverage:
|
||||
|
||||
**Backend Testing**
|
||||
- **Unit Tests**: Add unit tests for new features
|
||||
- **Integration Tests**: Add integration tests for APIs
|
||||
- **Performance Tests**: Add performance tests
|
||||
- **Security Tests**: Add security tests
|
||||
|
||||
**Frontend Testing**
|
||||
- **Component Tests**: Add component tests
|
||||
- **E2E Tests**: Add end-to-end tests
|
||||
- **Accessibility Tests**: Add accessibility tests
|
||||
- **Visual Tests**: Add visual regression tests
|
||||
|
||||
## 🆘 Getting Help
|
||||
|
||||
### Community Support
|
||||
Get help from the community:
|
||||
|
||||
**GitHub Discussions**
|
||||
- **Ask Questions**: Ask questions about implementation
|
||||
- **Share Ideas**: Share ideas and suggestions
|
||||
- **Get Feedback**: Get feedback on your contributions
|
||||
- **Help Others**: Help other contributors
|
||||
|
||||
**Discord Community**
|
||||
- **Real-time Chat**: Chat with other contributors
|
||||
- **Quick Questions**: Ask quick questions
|
||||
- **Collaboration**: Collaborate on features
|
||||
- **Mentorship**: Get mentorship from experienced contributors
|
||||
|
||||
### Documentation Resources
|
||||
Use documentation resources:
|
||||
|
||||
**Project Documentation**
|
||||
- **README**: Start with the main README
|
||||
- **API Docs**: Check API documentation
|
||||
- **Architecture Docs**: Understand system architecture
|
||||
- **Contributing Guide**: Follow this contributing guide
|
||||
|
||||
**External Resources**
|
||||
- **FastAPI Docs**: Learn FastAPI best practices
|
||||
- **React Docs**: Learn React best practices
|
||||
- **Python Docs**: Learn Python best practices
|
||||
- **TypeScript Docs**: Learn TypeScript best practices
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
### Immediate Actions (This Week)
|
||||
1. **Set up development environment** and get familiar with the codebase
|
||||
2. **Find a good first issue** to work on
|
||||
3. **Make your first contribution** following the guidelines
|
||||
4. **Join the community** and introduce yourself
|
||||
|
||||
### This Month
|
||||
1. **Contribute regularly** to the project
|
||||
2. **Help other contributors** and participate in code reviews
|
||||
3. **Take on larger features** and become a core contributor
|
||||
4. **Mentor new contributors** and help grow the community
|
||||
|
||||
## 🚀 Ready to Contribute?
|
||||
|
||||
**[Start with the development setup →](../getting-started/installation.md)**
|
||||
|
||||
---
|
||||
|
||||
*Questions? [Join our community](https://github.com/AJaySi/ALwrity/discussions) or [contact support](mailto:support@alwrity.com)!*
|
||||
Reference in New Issue
Block a user