Development Workflow¶

Small, Focused Commits: Make atomic commits with clear messages
Regular Pushes: Push changes frequently to backup work
Continuous Testing: Run tests locally during development
Code Quality: Follow style guidelines and best practices

Commit Message Guidelines¶

Follow Conventional Commits format:

type(scope): description

[optional body]

[optional footer]

Types: - feat: New feature - fix: Bug fix - docs: Documentation changes - style: Code style changes - refactor: Code refactoring - test: Adding or updating tests - chore: Maintenance tasks - perf: Performance improvements - ci: CI/CD changes

Examples:

feat(gallery): add species filtering functionality

Add dropdown filter to mosquito gallery allowing users to filter
by species family. Includes search functionality and clear filters option.

Closes #123

fix(classification): resolve model loading timeout

Increase timeout for PyTorch model loading from 5s to 15s to handle
slower devices. Add retry mechanism with exponential backoff.

Fixes #456

3. Pre-Pull Request Phase¶

Self-Review Checklist¶

Code follows project style guidelines
All tests pass locally
No debugging code or console logs
Documentation updated (if needed)
Commit messages follow conventions
Branch is up to date with main

Code Quality Checks¶

# Format code
flutter format .

# Analyze code
flutter analyze

# Run tests
flutter test

# Check test coverage
flutter test --coverage

Update Branch¶

# Rebase on latest main
git checkout main
git pull origin main
git checkout feature/mosquito-species-filter
git rebase main

# Or merge if rebase is not preferred
git merge main

4. Pull Request Creation¶

PR Preparation¶

Use PR Template: Fill out all sections completely
Clear Title: Use conventional commit format
Detailed Description: Explain what, why, and how
Link Issues: Reference related issues
Add Screenshots: For UI changes
Mark Draft: If not ready for review

PR Requirements¶

Code Review Process¶

Review Assignment¶

Automatic Assignment¶

Code Owners: Automatically assigned based on CODEOWNERS file
Team Members: Round-robin assignment for team members
Expertise-Based: Assign based on area of expertise

Manual Assignment¶

Complex Changes: Assign senior developers
Architecture Changes: Assign architects/leads
Security Changes: Assign security-focused reviewers
Performance Changes: Assign performance experts

Review Guidelines¶

For Authors¶

Respond Promptly: Address feedback within 24-48 hours
Ask Questions: Clarify unclear feedback
Separate Commits: Make review changes in separate commits
Update Tests: Ensure tests reflect changes
Be Receptive: Accept constructive feedback positively

For Reviewers¶

Timely Reviews: Complete reviews within 24-48 hours
Constructive Feedback: Be specific and helpful
Explain Reasoning: Provide context for suggestions
Test Functionality: Verify changes work as expected
Check Standards: Ensure code meets project standards

Review Checklist¶

Functionality¶

Code does what it's supposed to do
Edge cases are handled
Error handling is appropriate
Performance is acceptable

Code Quality¶

Code is readable and maintainable
Follows project conventions
No code duplication
Appropriate abstractions

Testing¶

Tests cover new functionality
Tests are meaningful and thorough
All tests pass
Test coverage is adequate

Documentation¶

Code is well-commented
API documentation updated
User documentation updated (if needed)
README updated (if needed)

Security¶

No security vulnerabilities
Input validation implemented
No hardcoded secrets
Proper error handling

Review Process Flow¶

flowchart TD
    A[PR Created] --> B[Automated Checks]
    B --> C{Checks Pass?}
    C -->|No| D[Fix Issues]
    D --> B
    C -->|Yes| E[Assign Reviewers]
    E --> F[Code Review]
    F --> G{Approved?}
    G -->|Changes Requested| H[Address Feedback]
    H --> F
    G -->|Approved| I[Merge PR]
    I --> J[Delete Branch]
    J --> K[Update Issue]

Testing Workflow¶

Test Types¶

Unit Tests¶

Purpose: Test individual functions/methods
Location: test/unit/
Coverage: All business logic and utilities
Run Command: flutter test test/unit/

Purpose: Test UI components
Location: test/widget/
Coverage: All custom widgets and screens
Run Command: flutter test test/widget/

Integration Tests¶

Purpose: Test complete user flows
Location: integration_test/
Coverage: Critical user journeys
Run Command: flutter test integration_test/

Testing Standards¶

Test Coverage Requirements¶

Minimum Coverage: 80% overall
Critical Code: 95% coverage required
New Code: 90% coverage required
UI Code: 70% coverage acceptable

Test Quality Standards¶

Descriptive Names: Tests should clearly describe what they test
Arrange-Act-Assert: Follow AAA pattern
Independent Tests: Tests should not depend on each other
Fast Execution: Unit tests should run quickly

Testing Workflow¶

Local Testing¶

# Run all tests
flutter test

# Run specific test suite
flutter test test/unit/services/
flutter test test/widget/screens/

# Run with coverage
flutter test --coverage
genhtml coverage/lcov.info -o coverage/html

# Run integration tests
flutter test integration_test/

CI Testing¶

Automated: All tests run on every PR
Multiple Platforms: Test on Android, iOS, Web
Performance Tests: Run performance benchmarks
Security Scans: Automated security vulnerability scanning

Release Process¶

Version Management¶

Semantic Versioning¶

We follow Semantic Versioning: - MAJOR: Breaking changes - MINOR: New features (backward compatible) - PATCH: Bug fixes (backward compatible)

Version Examples¶

1.0.0 → 1.0.1 (patch: bug fix)
1.0.1 → 1.1.0 (minor: new feature)
1.1.0 → 2.0.0 (major: breaking change)

Release Workflow¶

1. Release Planning¶

Feature Freeze: Stop adding new features
Bug Fix Phase: Focus on stability
Documentation Update: Ensure docs are current
Testing Phase: Comprehensive testing

2. Release Preparation¶

# Create release branch
git checkout -b release/1.2.0

# Update version numbers
# - pubspec.yaml
# - Android build.gradle
# - iOS Info.plist

# Update CHANGELOG.md
# Add release notes

# Commit changes
git commit -m "chore: prepare release 1.2.0"

3. Release Testing¶

Regression Testing: Test all major features
Performance Testing: Verify performance benchmarks
Device Testing: Test on various devices
User Acceptance Testing: Final user validation

4. Release Deployment¶

# Merge to main
git checkout main
git merge release/1.2.0

# Tag release
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# Build and deploy
flutter build apk --release
flutter build appbundle --release
flutter build ios --release

5. Post-Release¶

Monitor: Watch for issues in production
Hotfixes: Address critical issues quickly
Feedback: Collect user feedback
Planning: Plan next release cycle

Release Types¶

Regular Releases¶

Schedule: Monthly or bi-monthly
Content: New features and bug fixes
Testing: Full testing cycle
Documentation: Complete documentation update

Hotfix Releases¶

Trigger: Critical bugs or security issues
Timeline: Within 24-48 hours
Scope: Minimal changes, focused fixes
Testing: Focused testing on fix area

Beta Releases¶

Purpose: Early testing of major features
Audience: Beta testers and early adopters
Feedback: Collect feedback for final release
Stability: May contain known issues

Continuous Integration¶

CI Pipeline¶

Automated Checks¶

Code Quality
Linting with flutter analyze
Code formatting with flutter format
Dependency vulnerability scanning
Testing
Unit tests execution
Widget tests execution
Integration tests execution
Test coverage reporting
Build Verification
Android APK build
Android App Bundle build
iOS build (if applicable)
Web build
Security Scanning
Dependency vulnerability check
Code security analysis
License compliance check

CI Configuration¶

# Example GitHub Actions workflow
name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.29.3'

      - name: Install dependencies
        run: flutter pub get

      - name: Analyze code
        run: flutter analyze

      - name: Format check
        run: flutter format --dry-run --set-exit-if-changed .

      - name: Run tests
        run: flutter test --coverage

      - name: Upload coverage
        uses: codecov/codecov-action@v3

Quality Gates¶

PR Requirements¶

Merge Requirements¶

Branch is up to date
All conversations resolved
Required approvals received
No merge conflicts

Quality Assurance¶

Code Quality Metrics¶

Automated Metrics¶

Test Coverage: Minimum 80%
Code Complexity: Cyclomatic complexity < 10
Duplication: < 3% code duplication
Maintainability Index: > 70

Manual Review Points¶

Architecture Compliance: Follows MVVM pattern
Performance: No obvious performance issues
Security: No security vulnerabilities
Usability: Good user experience

Quality Tools¶

Static Analysis¶

Flutter Analyzer: Built-in Dart analyzer
Custom Lints: Project-specific lint rules
SonarQube: Code quality analysis (if used)

Testing Tools¶

Flutter Test: Built-in testing framework
Mockito: Mocking framework
Integration Test: Flutter integration testing

Performance Tools¶

Flutter DevTools: Performance profiling
Observatory: Dart VM profiling
Custom Benchmarks: App-specific performance tests

Deployment Process¶

Environment Strategy¶

Development Environment¶

Purpose: Active development and testing
Deployment: Automatic on feature branch push
Data: Test data and mock services
Access: Development team

Staging Environment¶

Purpose: Pre-production testing
Deployment: Automatic on main branch merge
Data: Production-like test data
Access: QA team and stakeholders

Production Environment¶

Purpose: Live application
Deployment: Manual trigger after approval
Data: Real user data
Access: End users

Deployment Workflow¶

Automated Deployment¶

# Example deployment workflow
name: Deploy
on:
  push:
    tags: ['v*']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Build APK
        run: flutter build apk --release

      - name: Build App Bundle
        run: flutter build appbundle --release

      - name: Deploy to Play Store
        uses: r0adkll/upload-google-play@v1
        with:
          serviceAccountJsonPlainText: ${{ secrets.SERVICE_ACCOUNT_JSON }}
          packageName: com.culicidaelab.mobile
          releaseFiles: build/app/outputs/bundle/release/app-release.aab
          track: production

Manual Deployment Steps¶

Pre-deployment Checks
Verify all tests pass
Check deployment checklist
Confirm rollback plan
Deployment Execution
Build release artifacts
Deploy to app stores
Update documentation
Post-deployment Verification
Verify deployment success
Monitor application health
Check user feedback

Rollback Procedures¶

Automatic Rollback¶

Health Checks: Monitor app crash rates
Performance Metrics: Watch for performance degradation
Error Rates: Monitor error frequency

Manual Rollback¶

# Rollback to previous version
git checkout v1.1.0
flutter build apk --release
# Deploy previous version

Conclusion¶

This development workflow ensures consistent code quality, efficient collaboration, and reliable releases. All team members should follow these guidelines to maintain project standards and deliver high-quality software.

For questions about the workflow or suggestions for improvements, please create an issue or start a discussion in the project repository.

Remember: The workflow is a living document that should evolve with the project's needs. Regular retrospectives help identify areas for improvement.

Development Workflow¶

Overview¶

Table of Contents¶

Branching Strategy¶

Branch Types¶

Main Branches¶

Supporting Branches¶

Branch Naming Conventions¶

Development Process¶

1. Planning Phase¶

Issue Creation¶

Issue Refinement¶

2. Development Phase¶

Starting Development¶

Development Workflow¶

Commit Message Guidelines¶

3. Pre-Pull Request Phase¶

Self-Review Checklist¶

Code Quality Checks¶

Update Branch¶

4. Pull Request Creation¶

PR Preparation¶

PR Requirements¶

Code Review Process¶

Review Assignment¶

Automatic Assignment¶

Manual Assignment¶

Review Guidelines¶

For Authors¶

For Reviewers¶

Review Checklist¶

Functionality¶

Code Quality¶

Testing¶

Documentation¶

Security¶

Review Process Flow¶

Testing Workflow¶

Test Types¶

Unit Tests¶

Widget Tests¶

Integration Tests¶

Testing Standards¶

Test Coverage Requirements¶

Test Quality Standards¶

Testing Workflow¶

Local Testing¶

CI Testing¶

Release Process¶

Version Management¶

Semantic Versioning¶

Version Examples¶

Release Workflow¶

1. Release Planning¶

2. Release Preparation¶

3. Release Testing¶

4. Release Deployment¶

5. Post-Release¶

Release Types¶

Regular Releases¶

Hotfix Releases¶

Beta Releases¶

Continuous Integration¶

CI Pipeline¶

Automated Checks¶

CI Configuration¶

Quality Gates¶

PR Requirements¶

Merge Requirements¶

Quality Assurance¶

Code Quality Metrics¶

Automated Metrics¶

Manual Review Points¶

Quality Tools¶

Static Analysis¶

Testing Tools¶

Performance Tools¶

Deployment Process¶

Environment Strategy¶

Development Environment¶