Skip to content

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
# 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 

cd backend
pip install -r requirements.txt

Environment Configuration 

# 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 

python start_alwrity_backend.py

Frontend Setup

Set up the frontend development environment:

Install Dependencies 

cd frontend
npm install

Environment Configuration 

# 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 

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 

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 

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 →

Questions? Join our community or contact support!