🤝 Contributing to VisoLearn-2

🌟 Welcome Contributors!

Thank you for your interest in contributing to VisoLearn-2! We welcome contributions from developers, educators, therapists, researchers, and anyone passionate about improving educational opportunities for children with autism.

📋 Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please read it to understand the expectations for all contributors.

🚀 Getting Started

Prerequisites

Before you begin contributing, ensure you have:

Python 3.8+ installed
Git for version control
Basic understanding of Python development
Familiarity with autism education principles (helpful but not required)

Setting Up Your Development Environment

# Clone the repository
git clone https://github.com/visolearn/visolearn-2.git
cd visolearn-2

# Set up virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Set up pre-commit hooks
pip install pre-commit
pre-commit install

📝 How to Contribute

Reporting Issues

Before submitting an issue:

Check existing issues to avoid duplicates
Ensure you're using the latest version
Provide clear reproduction steps

Issue Template:

### Description
Clear description of the issue

### Steps to Reproduce
1. Go to...
2. Click on...
3. Observe...

### Expected Behavior
What should happen

### Actual Behavior
What actually happens

### Environment
- OS: [e.g., Windows 10, macOS 12]
- Python version: [e.g., 3.11]
- VisoLearn-2 version: [e.g., 2.3.1]

### Additional Context
Screenshots, logs, or other relevant information

Suggesting Features

Feature Request Template:

### Feature Description
Clear description of the proposed feature

### Use Case
Who would use this and why

### Benefits
How this improves the application

### Implementation Ideas
Optional: Suggestions for implementation

### Related Issues
Links to related issues or discussions

Contributing Code

Branch Strategy

# Create a feature branch
git checkout -b feature/your-feature-name

# Or create a bugfix branch
git checkout -b bugfix/issue-description

Branch Naming Conventions:

feature/ - New features
bugfix/ - Bug fixes
docs/ - Documentation improvements
refactor/ - Code refactoring
test/ - Testing improvements

Commit Guidelines

Commit Message Format:

<type>(<scope>): <description>

<body>

<footer>

Types:

feat - New feature
fix - Bug fix
docs - Documentation changes
style - Code style changes
refactor - Code refactoring
test - Adding or modifying tests
chore - Build process or auxiliary tool changes

Examples:

git commit -m "feat(image-generation): add support for new image styles"
git commit -m "fix(evaluation): correct semantic analysis scoring"
git commit -m "docs(usage): add examples for story module"

Pull Request Process

Fork the repository and create your branch
Make your changes following our coding standards
Write tests for new functionality
Update documentation if applicable
Run tests to ensure nothing breaks
Submit a pull request with a clear description

Pull Request Template:

### Description
Clear description of the changes

### Related Issues
Fixes #issue-number or addresses #issue-number

### Changes Made
- List of specific changes
- Files modified
- New features added

### Testing
- Tests added
- Manual testing performed
- Edge cases considered

### Checklist
- [ ] Code follows style guidelines
- [ ] Tests pass successfully
- [ ] Documentation updated
- [ ] Changes are backward compatible
- [ ] No breaking changes introduced

📚 Coding Standards

Python Style Guide

We follow PEP 8 with some additional guidelines:

Naming Conventions:

snake_case for variables and functions
CamelCase for class names
UPPER_CASE for constants
_single_leading_underscore for protected members
__double_leading_underscore for private members

Code Formatting:

4 spaces for indentation (no tabs)
79 characters per line maximum
2 blank lines around top-level functions/classes
1 blank line between methods
Consistent quote style (single quotes preferred)

Docstrings:

def example_function(param1: str, param2: int) -> bool:
    """
    Brief description of the function.
    
    Args:
        param1 (str): Description of parameter 1
        param2 (int): Description of parameter 2
        
    Returns:
        bool: Description of return value
        
    Raises:
        ValueError: If parameters are invalid
        
    Examples:
        >>> example_function("test", 42)
        True
    """
    # Function implementation
    pass

Type Hints

Use Python type hints for better code clarity:

from typing import Dict, List, Optional, Tuple

def process_data(
    input_data: List[Dict[str, Any]],
    config: Optional[Dict[str, str]] = None
) -> Tuple[bool, str]:
    """Process input data with optional configuration."""
    # Implementation
    pass

Error Handling

Best Practices:

Use specific exception types
Provide meaningful error messages
Log errors appropriately
Don't expose sensitive information

try:
    # Risky operation
    result = risky_function()
except ValueError as e:
    logger.error(f"Validation error in risky_function: {str(e)}")
    raise UserFriendlyError("Please check your input and try again")
except Exception as e:
    logger.error(f"Unexpected error in risky_function: {str(e)}", exc_info=True)
    raise SystemError("An unexpected error occurred. Please try again later.")

🧪 Testing

Test Requirements

Test Coverage: Aim for 85%+ code coverage
Test Types: Unit tests, integration tests, end-to-end tests
Test Quality: Tests should be reliable and maintainable

Writing Tests

Test Structure:

import pytest
from models.image_generation import generate_image

def test_generate_image_success():
    """Test successful image generation."""
    # Setup
    prompt = "test image"
    
    # Exercise
    result = generate_image(prompt)
    
    # Verify
    assert result is not None
    assert isinstance(result, Image.Image)
    assert result.size == (1024, 1024)

def test_generate_image_invalid_prompt():
    """Test image generation with invalid prompt."""
    # Setup
    invalid_prompt = ""
    
    # Exercise & Verify
    with pytest.raises(ValueError):
        generate_image(invalid_prompt)

Running Tests

# Run all tests
pytest tests/

# Run tests with coverage
pytest --cov=./ --cov-report=html tests/

# Run specific test module
pytest tests/test_image_generation.py

# Run tests with verbose output
pytest -v tests/

📁 Documentation

Documentation Standards

Markdown Format:

Use clear, concise language
Organize content logically
Use headings appropriately
Include code examples
Add visual aids when helpful

Docstring Format:

"""
Module/Class/Function documentation

Extended description explaining purpose and usage.

Attributes:
    attribute1 (type): Description
    attribute2 (type): Description

Methods:
    method1(): Description
    method2(): Description

Examples:
    >>> example_usage()
    result
"""

Documentation Updates

When contributing code:

Update relevant documentation
Add examples for new features
Document API changes
Update usage guides

🔧 Development Workflow

Feature Development

Discuss the feature in an issue
Design the implementation approach
Implement the feature with tests
Document the new functionality
Submit a pull request
Review and iterate based on feedback

Bug Fixing

Reproduce the issue
Identify the root cause
Implement the fix
Test thoroughly
Document the fix
Submit a pull request

Code Review Process

Review Checklist:

Code follows style guidelines
Tests are comprehensive
Documentation is updated
Changes are backward compatible
Performance is acceptable
Security considerations addressed

🌐 Community Guidelines

Communication

Be respectful and professional
Use inclusive language
Provide constructive feedback
Be patient and helpful
Respect different viewpoints

Collaboration

Work together on complex issues
Share knowledge and expertise
Help new contributors
Document decisions
Celebrate achievements

📊 Contribution Areas

Development

Current Priorities:

✅ Image generation enhancements
✅ Evaluation algorithm improvements
✅ Story generation refinements
✅ Accessibility features
✅ Performance optimizations

Research

Research Opportunities:

AI model effectiveness studies
User experience research
Educational impact analysis
Autism-specific learning patterns

Documentation

Documentation Needs:

User guides and tutorials
API documentation
Technical reference
Best practices guides
Case studies

Testing

Testing Focus Areas:

Edge case testing
Performance testing
Accessibility testing
Cross-platform testing
Regression testing

Community

Community Contributions:

User support
Feature suggestions
Bug reporting
Translation efforts
Outreach programs

🎯 First Contributions

Good First Issues

Look for issues labeled:

good first issue - Beginner-friendly tasks
help wanted - Tasks needing assistance
documentation - Documentation improvements
bug - Bug fixes

Mentorship

We offer mentorship for new contributors:

Guidance on project structure
Code review assistance
Best practices advice
Architecture explanations

🛡️ Security

Security Guidelines

Never commit API keys or sensitive data
Use environment variables for secrets
Follow secure coding practices
Report security vulnerabilities responsibly
Keep dependencies updated

Reporting Vulnerabilities

If you discover a security vulnerability:

Do not create a public issue
Email: security@visolearn.org
Include detailed reproduction steps
Allow time for response and fix

📈 Performance

Performance Guidelines

Optimize critical paths
Use caching appropriately
Minimize API calls
Implement efficient algorithms
Profile before optimizing

Performance Testing

import time
from functools import wraps

def time_function(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        start = time.time()
        result = func(*args, **kwargs)
        end = time.time()
        print(f"{func.__name__} took {end - start:.3f}s")
        return result
    return wrapper

🌍 Internationalization

Translation Guidelines

Use clear, simple language
Avoid idioms and cultural references
Provide context for translators
Test translations thoroughly
Respect regional differences

Localization Process

Extract translatable strings
Create translation templates
Translate content
Review translations
Integrate and test

📚 Learning Resources

For New Contributors

Recommended Learning:

Python programming basics
Autism education principles
AI and machine learning concepts
Software development best practices
Accessibility guidelines

Project-Specific Resources

Key Documentation:

🎓 Recognition

Contributor Recognition

We value all contributions and recognize contributors through:

GitHub Contributors page
Release Notes acknowledgments
Community Spotlights
Special Badges for significant contributions

Contribution Tiers

Tier	Criteria	Recognition
Bronze	1-5 contributions	Name in contributors list
Silver	6-20 contributions	Featured contributor badge
Gold	20+ contributions	Core contributor status
Platinum	50+ contributions	Project leadership opportunities

📞 Getting Help

Support Channels

For Contributors:

GitHub Discussions: Technical discussions
Slack/Discord: Real-time communication
Email: contributor-support@visolearn.org
Mentorship Program: One-on-one guidance

Common Questions

Q: How do I get started? A: Check our "good first issue" labels and join our community channels.

Q: What if I'm not a developer? A: We welcome non-code contributions like documentation, testing, and research.

Q: How long does code review take? A: Typically 1-3 days, depending on complexity and reviewer availability.

Q: Can I work on multiple features at once? A: We recommend focusing on one feature at a time for better quality.

🎯 Next Steps

Ready to contribute?

Fork the repository and set up your environment
Explore open issues and find something interesting
Join our community channels for discussion
Start small with documentation or simple bug fixes
Grow your skills and take on more complex tasks

🙏 Thank You!

Your contributions help make VisoLearn-2 better for children with autism worldwide. We appreciate your time, expertise, and passion for this important cause.

Together, we can create meaningful educational experiences that empower children with autism to develop communication skills, enhance learning abilities, and build confidence.

Welcome to the VisoLearn-2 community! 🎉

This contributing guide provides comprehensive information for anyone interested in helping improve VisoLearn-2. Whether you're a developer, educator, researcher, or enthusiast, there are many ways to contribute to this important project.

FilesExpand file tree

contributing.md

Latest commit

History