Contributing to Flutter Starter

First off, thank you for considering contributing to Flutter Starter! 🎉

This document provides guidelines and instructions for contributing to this project. Following these guidelines helps communicate that you respect the time of the developers managing and developing this open source project.

Code of Conduct

This project adheres to a Code of Conduct that all contributors are expected to follow. Please be respectful and considerate of others when contributing.

Our Standards

✅ Be respectful and inclusive
✅ Welcome newcomers and help them learn
✅ Focus on constructive feedback
✅ Respect different viewpoints and experiences

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the issue list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible:

Before Submitting a Bug Report

Check the documentation - The issue might already be documented
Check existing issues - The bug might have already been reported
Test with the latest version - Make sure you're using the latest code

How to Report a Bug

Use the bug report template (if available on GitHub)
Include the following information:
- Flutter version (flutter --version)
- Dart version
- Platform (Android/iOS/Web/Linux/macOS/Windows)
- Steps to reproduce
- Expected behavior
- Actual behavior
- Screenshots (if applicable)
- Error messages or logs

Example Bug Report

**Flutter Version:** 3.24.0
**Dart Version:** 3.4.0
**Platform:** Android

**Steps to Reproduce:**
1. Open the app
2. Navigate to Tasks screen
3. Try to create a new task
4. App crashes

**Expected Behavior:**
Task should be created successfully

**Actual Behavior:**
App crashes with error: [error message]

**Logs:**
[Paste relevant logs here]

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, please include:

Clear and descriptive title
Detailed description of the enhancement
Use case - Why is this enhancement useful?
Possible implementation (if you have ideas)
Alternatives considered (if any)

Example Enhancement Suggestion

**Enhancement:** Add dark mode toggle in settings

**Description:**
Add a toggle switch in the settings screen to allow users to switch between light and dark themes.

**Use Case:**
Users prefer dark mode for better battery life and eye comfort, especially in low-light conditions.

**Possible Implementation:**
- Add a Switch widget in SettingsScreen
- Use ThemeModeProvider to toggle between light/dark/system
- Persist preference in SharedPreferences

Pull Requests

Pull requests are the best way to propose changes to the codebase. We actively welcome your pull requests:

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes
Follow our coding standards
Write or update tests
Update documentation
Commit your changes (see Commit Message Guidelines)
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Pull Request Checklist

Before submitting a PR, make sure:

Code follows the project's style guidelines
All tests pass (flutter test)
Code analysis passes (flutter analyze)
Documentation is updated (if needed)
Commit messages follow the guidelines
PR description is clear and descriptive
Related issues are referenced (if any)

Development Setup

Prerequisites

Flutter SDK (>=3.0.0)
Dart SDK (>=3.0.0)
Git
IDE (VS Code, Android Studio, or IntelliJ IDEA)

Setup Steps

Fork and clone the repository

git clone https://github.com/your-username/flutter_starter.git
cd flutter_starter

Install dependencies
```
flutter pub get
```

Generate code (Freezed, JSON serialization)

flutter pub run build_runner build --delete-conflicting-outputs

Set up environment configuration

cp .env.example .env
# Edit .env with your configuration

Run the app
```
flutter run
```
Run tests
```
flutter test
```

Development Workflow

Branch Naming

Use the following naming convention:

<type>/<short-description>

Examples:
- feature/add-product-search
- fix/auth-token-refresh
- refactor/extract-common-widgets
- docs/update-onboarding-guide
- test/add-auth-integration-tests

Types:

feature/ - New features
fix/ - Bug fixes
refactor/ - Code refactoring
docs/ - Documentation changes
test/ - Test additions/changes
chore/ - Maintenance tasks

Workflow Steps

Create a feature branch from main

git checkout main
git pull origin main
git checkout -b feature/your-feature-name

Make your changes and commit frequently

git add .
git commit -m "feat: add product listing screen"

Keep your branch up to date

git checkout main
git pull origin main
git checkout feature/your-feature-name
git merge main  # or git rebase main

Push your branch

git push origin feature/your-feature-name

Create a Pull Request on GitHub

Pre-PR quality gate (non-platform)

Before opening a PR, run (same scope as CI for Dart — no platform builds):

./scripts/dev/audit_template.sh

This runs scoped dart format --check, flutter analyze, and flutter test. On Windows without Bash, run the commands in docs/guides/testing/testing-summary.md manually.

GitHub branch protection (recommended)

On the default branch (for example main), you can require the Quality gate status before merge:

Repository Settings → Rules → Rulesets (or Branches → Branch protection rules, depending on your org).
Add a rule for main (or your default branch).
Enable Require status checks to pass before merging.
Add the check named Quality gate (the single job in .github/workflows/ci.yml: format, analyze, then unit tests on one runner to limit Actions minutes for forks).

If you later split CI into parallel jobs for speed, you can require each job or add an aggregate job again for one required check.

Coding Standards

Code Style

Follow Dart Style Guide
Use very_good_analysis linting rules (already configured)
Run flutter analyze before committing
Format Dart sources (not the whole repo — skips build/): ./scripts/dev/format_dart.sh or dart format lib test integration_test tool bricks

Architecture

Follow Clean Architecture principles
Separate concerns: Domain → Data → Presentation
Use dependency injection (Riverpod)
Keep business logic in domain layer
Keep UI logic in presentation layer

Code Organization

lib/
├── core/           # Infrastructure (config, network, storage, etc.)
├── features/       # Feature modules (Clean Architecture)
│   └── feature_name/
│       ├── data/
│       ├── domain/
│       └── presentation/
└── shared/         # Shared resources (widgets, theme, extensions)

Naming Conventions

Files: snake_case.dart
Classes: PascalCase
Variables/Functions: camelCase
Constants: lowerCamelCase or UPPER_SNAKE_CASE
Private members: _leadingUnderscore

Best Practices

✅ Use const constructors when possible
✅ Prefer final over var
✅ Use null safety properly
✅ Add documentation comments for public APIs
✅ Keep functions small and focused
✅ Avoid deep nesting (max 3-4 levels)
✅ Use meaningful variable names
✅ Extract magic numbers to constants

Commit Message Guidelines

We follow Conventional Commits specification.

Format

<type>(<scope>): <subject>

<body>

<footer>

Types

feat - New feature
fix - Bug fix
docs - Documentation changes
style - Code style changes (formatting, etc.)
refactor - Code refactoring
test - Test additions/changes
chore - Maintenance tasks
perf - Performance improvements
ci - CI/CD changes
build - Build system or external dependencies (e.g. Gradle, pods)
revert - Reverts a previous commit

Examples

feat(auth): add token refresh functionality

fix(network): handle connection timeout errors

docs(guides): update onboarding instructions

refactor(products): extract product card widget

test(auth): add login use case tests

Guidelines

Use present tense ("add" not "added")
Keep subject line under 50 characters
Capitalize first letter of subject
No period at end of subject
Reference issues in footer: Closes #123

Testing Guidelines

Test Structure

Tests should mirror the source code structure:

test/
├── core/
├── features/
│   └── feature_name/
│       ├── data/
│       ├── domain/
│       └── presentation/
└── helpers/

Test Types

Unit Tests - Test individual functions/classes
Widget Tests - Test UI components
Integration Tests - Test complete flows

Writing Tests

✅ Write tests for new features
✅ Write tests for bug fixes
✅ Aim for high test coverage
✅ Use descriptive test names
✅ Follow AAA pattern (Arrange, Act, Assert)
✅ Mock external dependencies

Example Test

group('LoginUseCase', () {
  test('should return Success when login is successful', () async {
    // Arrange
    final mockRepository = MockAuthRepository();
    when(mockRepository.login(any, any))
        .thenAnswer((_) async => Right(mockUser));
    final useCase = LoginUseCase(mockRepository);

    // Act
    final result = await useCase('email@example.com', 'password');

    // Assert
    expect(result.isSuccess, true);
    verify(mockRepository.login('email@example.com', 'password')).called(1);
  });
});

Running Tests

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

# Run specific test file
flutter test test/features/auth/domain/usecases/login_test.dart

Documentation

Code Documentation

Add documentation comments for public APIs
Use /// for documentation comments
Document parameters, return values, and exceptions
Include code examples when helpful

Example

/// Authenticates a user with email and password.
///
/// Returns [Result<User>] containing either:
/// - [Success<User>] with authenticated user on success
/// - [ResultFailure] with error details on failure
///
/// Throws [Exception] if authentication service is unavailable.
///
/// Example:
/// ```dart
/// final result = await loginUseCase('email@example.com', 'password');
/// result.when(
///   success: (user) => print('Logged in: ${user.email}'),
///   failure: (error) => print('Error: $error'),
/// );
/// ```
Future<Result<User>> call(String email, String password) async {
  // Implementation
}

Documentation Updates

When adding new features:

✅ Update README.md if needed
✅ Add/update API documentation
✅ Update guides if workflow changes
✅ Add examples if introducing new patterns

Review Process

What to Expect

Automated Checks - GitHub Actions runs Quality gate (format → analyze → tests on one Ubuntu runner) for branch protection
Code Review - Maintainers will review your code
Feedback - You may receive suggestions for improvements
Iteration - You may need to make changes based on feedback

Responding to Feedback

Be open to suggestions
Ask questions if something is unclear
Make requested changes promptly
Update your PR when changes are made

Getting Help

If you need help:

Check the documentation - docs/ folder
Search existing issues - Someone might have asked the same question
Open a discussion - Use GitHub Discussions for questions
Ask in PR comments - If related to a specific PR

Recognition

Contributors will be recognized in:

README.md (Contributors section)
Release notes (for significant contributions)
Project documentation

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank You! 🙏

Thank you for taking the time to contribute to Flutter Starter! Your contributions make this project better for everyone.

Questions? Open an issue or start a discussion on GitHub.

FilesExpand file tree

CONTRIBUTING.md

Latest commit

History