LearnIT/docs/CONTRIBUTING.md

Contributing Guidelines - AI Study Assistant

⚠️ ATUALIZADO: Este documento foi corrigido para refletir a arquitetura REAL (Flutter + Firebase apenas).

Nota: Não existe backend Node.js nem Python RAG engine. Toda a lógica está no Flutter.

🤝 HOW TO CONTRIBUTE

---

📋 OVERVIEW

Thank you for your interest in contributing to the AI Study Assistant! This guide provides information on how to contribute to our Flutter + Firebase project.

---

🚀 GETTING STARTED

Prerequisites

• Git: Version 2.30 or higher
• Flutter: Version 3.11.5+ (with Dart 3.0+)
• Firebase CLI: Latest version
• Code Editor: VS Code recommended
• Note: No Node.js or Python required (backend is Firebase BaaS)

Development Environment Setup

1. Fork the repository
2. Clone your fork locally
3. Set up development environment
4. Install dependencies
5. Run tests to verify setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/teachit.git
cd teachit

# Install Flutter dependencies only
flutter pub get

# Note: No backend dependencies to install
# No Cloud Functions (Firebase BaaS is used)
# No Python RAG engine (implemented in Dart)

# Run tests
flutter test

---

🌟 CONTRIBUTION TYPES

Code Contributions

• Bug Fixes: Resolve reported issues
• New Features: Add functionality
• Performance: Optimize existing code
• Documentation: Improve documentation
• Testing: Add or improve tests

Non-Code Contributions

• Bug Reports: Report issues with detailed information
• Feature Requests: Suggest new features
• Documentation: Improve guides and documentation
• Community: Help others in discussions
• Translation: Help with internationalization

---

🔄 DEVELOPMENT WORKFLOW

Branch Strategy

main                    # Production branch
├── develop             # Development branch
├── feature/feature-name # Feature branches
├── hotfix/issue-number  # Hotfix branches
└── release/version     # Release branches

Workflow Steps

1. Create Issue: Discuss changes in an issue first
2. Create Branch: Create feature branch from develop
3. Develop: Implement changes with proper testing
4. Test: Ensure all tests pass
5. Submit PR: Create pull request to develop
6. Review: Get code review and address feedback
7. Merge: Merge after approval
8. Deploy: Automatic deployment to staging

Branch Naming Conventions

• Feature: feature/description-of-feature
• Bug Fix: fix/issue-number-description
• Hotfix: hotfix/issue-number-description
• Release: release/version-number
• Documentation: docs/description-of-change

---

📝 CODING STANDARDS

General Guidelines

• Consistency: Follow existing code style
• Clarity: Write clear, readable code
• Comments: Add comments for complex logic
• Testing: Write tests for new functionality
• Documentation: Update relevant documentation

Flutter/Dart Standards

Code Style

// Use meaningful variable names
final List<LearningConcept> concepts = [];

// Use const for compile-time constants
const int maxRetries = 3;

// Use proper naming conventions
class LearningAnalytics {
  Future<void> trackProgress() async {
    // Implementation
  }
}

// Use async/await for asynchronous operations
Future<void> loadData() async {
  final data = await apiService.getData();
  processData(data);
}

Widget Structure

class CustomWidget extends StatelessWidget {
  final String title;
  final VoidCallback? onTap;
  
  const CustomWidget({
    required this.title,
    this.onTap,
    Key? key,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Container(
      child: Text(title),
    );
  }
}

State Management

// Use Riverpod providers
final learningStateProvider = StateNotifierProvider<LearningStateNotifier, LearningState>(
  (ref) => LearningStateNotifier(),
);

// Use proper provider naming
final authProvider = Provider<AuthService>((ref) => AuthService());

TypeScript/Node.js Standards

Code Style

// Use interfaces for type definitions
interface User {
  id: string;
  email: string;
  role: UserRole;
}

// Use proper error handling
async function getUser(id: string): Promise<User> {
  try {
    const user = await userRepository.findById(id);
    if (!user) {
      throw new Error('User not found');
    }
    return user;
  } catch (error) {
    console.error('Error fetching user:', error);
    throw error;
  }
}

// Use proper function naming
export class UserService {
  async createUser(userData: CreateUserRequest): Promise<User> {
    // Implementation
  }
}

Python Standards

Code Style

# Use type hints
from typing import List, Optional

class VectorSearchService:
    def __init__(self, dimension: int = 384) -> None:
        self.dimension = dimension
    
    def search(self, query: np.ndarray, k: int = 10) -> List[Tuple[int, float]]:
        """Search for similar vectors."""
        # Implementation
        pass

# Use proper docstrings
def process_text(text: str) -> ProcessedText:
    """
    Process text for embedding.
    
    Args:
        text: The input text to process
        
    Returns:
        ProcessedText: The processed text object
    """
    # Implementation
    pass

---

🧪 TESTING GUIDELINES

Test Structure

test/
├── unit/           # Unit tests
├── widget/         # Widget tests
├── integration/    # Integration tests
├── e2e/           # End-to-end tests
└── fixtures/       # Test data

Flutter Testing

// Unit test example
void main() {
  group('LearningStateNotifier', () {
    test('should update learning state correctly', () async {
      final notifier = LearningStateNotifier();
      
      await notifier.updateProgress('mathematics', 0.8);
      
      expect(notifier.state.mastery['mathematics'], equals(0.8));
    });
    
    test('should handle invalid input gracefully', () async {
      final notifier = LearningStateNotifier();
      
      expect(() => notifier.updateProgress('', -1.0), throwsA(isA<ArgumentError>));
    });
  });
}

// Widget test example
void main() {
  testWidgets('LearningProgressCard displays correctly', (WidgetTester tester) async {
    await tester.pumpWidget(
      MaterialApp(
        home: LearningProgressCard(
          concept: 'Derivatives',
          mastery: 0.75,
        ),
      ),
    );
    
    expect(find.text('Derivatives'), findsOneWidget);
    expect(find.text('75%'), findsOneWidget);
  });
}

Backend Testing

// Unit test example
describe('UserService', () => {
  let userService: UserService;
  let mockRepository: jest.Mocked<UserRepository>;
  
  beforeEach(() => {
    mockRepository = new MockUserRepository();
    userService = new UserService(mockRepository);
  });
  
  it('should create user successfully', async () => {
    const userData = {
      email: 'test@example.com',
      role: 'student',
    };
    
    const expectedUser = { id: '123', ...userData };
    mockRepository.create.mockResolvedValue(expectedUser);
    
    const result = await userService.createUser(userData);
    
    expect(result).toEqual(expectedUser);
    expect(mockRepository.create).toHaveBeenCalledWith(userData);
  });
});

Python Testing

# Unit test example
import pytest
from unittest.mock import Mock, patch

class TestVectorSearchService:
    def setup_method(self):
        self.service = VectorSearchService(dimension=384)
        self.mock_index = Mock()
        self.service.index = self.mock_index
    
    def test_search_returns_correct_results(self):
        # Arrange
        query = np.random.rand(384)
        expected_results = [(1, 0.95), (2, 0.87)]
        self.mock_index.search.return_value = (np.array([0.95, 0.87]), np.array([1, 2]))
        
        # Act
        results = self.service.search(query, k=2)
        
        # Assert
        assert len(results) == 2
        assert results == expected_results
        self.mock_index.search.assert_called_once()

---

📖 DOCUMENTATION STANDARDS

Documentation Types

• API Documentation: Endpoint specifications
• Code Comments: Inline documentation
• README Files: Project and module documentation
• User Guides: End-user documentation
• Developer Guides: Technical documentation

Writing Guidelines

• Clear and Concise: Use simple, clear language
• Examples: Include code examples
• Structure: Use proper headings and formatting
• Consistency: Follow existing documentation style
• Accuracy: Ensure information is up-to-date

Code Comments

/// A service for managing learning analytics and progress tracking.
/// 
/// This service provides functionality to:
/// - Track student progress across concepts
/// - Calculate mastery levels
/// - Generate learning recommendations
/// 
/// Example:
/// ```dart
/// final analytics = LearningAnalyticsService();
/// await analytics.trackProgress('mathematics', 0.8);
/// ```
class LearningAnalyticsService {
  /// The maximum number of concepts to track per student.
  static const int maxConceptsPerStudent = 50;
  
  /// Tracks progress for a specific concept.
  /// 
  /// [studentId] The unique identifier for the student
  /// [concept] The concept being tracked
  /// [mastery] The mastery level (0.0 to 1.0)
  /// 
  /// Throws [ArgumentError] if mastery is not in valid range
  Future<void> trackProgress(
    String studentId, 
    String concept, 
    double mastery
  ) async {
    if (mastery < 0.0 || mastery > 1.0) {
      throw ArgumentError('Mastery must be between 0.0 and 1.0');
    }
    
    // Implementation
  }
}

---

🔍 CODE REVIEW PROCESS

Review Criteria

• Functionality: Does the code work as expected?
• Code Quality: Is the code well-written and maintainable?
• Testing: Are there adequate tests?
• Documentation: Is the code properly documented?
• Performance: Is the code efficient?
• Security: Is the code secure?

Review Guidelines

• Be Constructive: Provide helpful, specific feedback
• Be Thorough: Review all aspects of the code
• Be Respectful: Maintain a professional tone
• Be Timely: Respond to reviews promptly

Pull Request Template

## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] All tests pass
- [ ] New tests added
- [ ] Manual testing completed

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes (or documented)

---

🐛 BUG REPORTING

Bug Report Template

## Bug Description
Clear and concise description of the bug

## Steps to Reproduce
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

## Expected Behavior
What you expected to happen

## Actual Behavior
What actually happened

## Screenshots
If applicable, add screenshots

## Environment
- OS: [e.g. iOS 15.0, Android 11, Windows 10]
- App Version: [e.g. 1.0.0]
- Browser: [e.g. Chrome 96.0]
- Device: [e.g. iPhone 12, Samsung Galaxy S21]

## Additional Context
Add any other context about the problem here

Bug Severity Levels

• Critical: Blocks core functionality
• High: Significant impact on user experience
• Medium: Minor issues with workarounds
• Low: Cosmetic or minor issues

---

💡 FEATURE REQUESTS

Feature Request Template

## Feature Description
Clear and concise description of the feature

## Problem Statement
What problem does this feature solve?

## Proposed Solution
How should this feature work?

## Alternatives
What other solutions have you considered?

## Additional Context
Add any other context about the feature here

Feature Priority Levels

• High: Core functionality needed
• Medium: Important enhancement
• Low: Nice to have feature

---

🌍 INTERNATIONALIZATION

Translation Guidelines

• Languages: Currently supporting English, Portuguese, Spanish
• Translation Files: Located in lib/l10n/
• Translation Keys: Use descriptive keys
• Context: Provide context for translators

Adding New Language

1. Create new .arb file in lib/l10n/
2. Translate all keys from existing files
3. Update app_localizations.dart
4. Test with new language

---

🔐 SECURITY GUIDELINES

Security Considerations

• No Hardcoded Secrets: Use environment variables
• Input Validation: Validate all user inputs
• Authentication: Use proper authentication
• Authorization: Implement proper access controls
• Data Protection: Encrypt sensitive data

Reporting Security Issues

• Private: Report security issues privately
• Email: security@teachit.app
• PGP Key: Available on request
• Response: Within 24 hours

---

📊 PERFORMANCE GUIDELINES

Performance Considerations

• Efficiency: Write efficient code
• Memory: Manage memory usage
• Network: Optimize network requests
• UI: Maintain smooth UI performance
• Battery: Consider battery usage

Performance Testing

• Profiling: Use profiling tools
• Benchmarks: Measure performance
• Monitoring: Track performance metrics
• Optimization: Optimize bottlenecks

---

🤝 COMMUNITY GUIDELINES

Code of Conduct

• Respect: Treat everyone with respect
• Inclusive: Be inclusive and welcoming
• Professional: Maintain professional conduct
• Helpful: Help others learn and grow

Communication Channels

• GitHub Issues: For bug reports and feature requests
• GitHub Discussions: For general discussions
• Discord: For real-time chat (if available)
• Email: For private communications

Getting Help

• Documentation: Check documentation first
• Issues: Search existing issues
• Discussions: Ask in discussions
• Maintainers: Contact maintainers directly

---

📋 RELEASE PROCESS

Release Checklist

• All tests pass
• Documentation updated
• Version number updated
• Change log updated
• Security review completed
• Performance testing completed
• Integration testing completed

Release Types

• Major: Significant new features (X.0.0)
• Minor: New features and improvements (X.Y.0)
• Patch: Bug fixes and security updates (X.Y.Z)

Version Numbering

• Semantic Versioning: Follow SemVer
• Breaking Changes: Increment major version
• New Features: Increment minor version
• Bug Fixes: Increment patch version

---

🏆 RECOGNITION

Contributor Recognition

• Contributors List: All contributors listed
• Release Notes: Contributors mentioned in release notes
• Community: Recognition in community forums
• Swag: Available for significant contributions

Types of Contributions

• Code: Code contributions
• Documentation: Documentation improvements
• Design: UI/UX contributions
• Testing: Testing and quality assurance
• Community: Community support and help

---

📚 RESOURCES

Learning Resources

• Flutter Documentation
• Firebase Documentation
• TypeScript Handbook
• Python Style Guide
• Git Handbook

Development Tools

• IDE: VS Code with Flutter and Dart extensions
• Testing: Flutter Test, Jest, Pytest
• Linting: Dart Analysis, ESLint, Flake8
• Formatting: Dart Format, Prettier, Black
• Debugging: Flutter DevTools, Chrome DevTools

Community Resources

• Flutter Community
• Firebase Community
• Stack Overflow
• Discord Server

---

📞 GETTING HELP

Ways to Get Help

• Documentation: Check existing documentation
• Issues: Search existing issues
• Discussions: Ask in GitHub discussions
• Email: Contact maintainers at dev@teachit.app
• Discord: Join our Discord server

When to Ask for Help

• Setup Issues: Problems with development environment
• Code Issues: Help with code implementation
• Testing: Help with writing tests
• Documentation: Help with documentation
• Review: Request code review

---

✅ CONTRIBUTOR CHECKLIST

Before Contributing

• Read contributing guidelines
• Set up development environment
• Understand project structure
• Check existing issues and discussions
• Choose appropriate contribution type

During Development

• Follow coding standards
• Write tests for new code
• Update documentation
• Test thoroughly
• Keep commits small and focused

Before Submitting

• Run all tests
• Update change log
• Write clear commit messages
• Create descriptive pull request
• Address review feedback

---

🎉 THANK YOU

Thank you for contributing to the AI Study Assistant! Your contributions help make educational technology better for students and teachers worldwide.

Every contribution, no matter how small, is valued and appreciated. Together, we're building a platform that makes learning more accessible, engaging, and effective for everyone.

---

Last Updated: 2026-05-06 Version: 1.0.0 Community Team: Open Source & Collaboration