Contributing to CNVRT

Before you begin, make sure you have the following installed:

• Flutter SDK ^3.8.1 (Installation Guide)
• Dart SDK ^3.8.1 (bundled with Flutter)
• Android Studio with Android SDK (for Android builds)
• Xcode (for iOS builds, macOS only)
• Git
• A code editor (Android Studio, VS Code, IntelliJ IDEA)

1. Fork and Clone

# Fork the repository on GitHub, then clone your fork
git clone https://github.com/YOUR_USERNAME/cnvrt.git
cd cnvrt

# Add upstream remote
git remote add upstream https://github.com/wesleybliss/cnvrt.git

2. Verify Environment

# Check Flutter installation
flutter doctor -v

# Resolve any issues reported by flutter doctor
flutter doctor --android-licenses  # Accept Android licenses if needed

3. Install Dependencies

# Clean and install dependencies
flutter clean
flutter pub get

# Generate code (Riverpod providers, Drift database, etc.)
flutter pub run build_runner build --delete-conflicting-outputs

4. Run the App

# Connect a device or start an emulator, then:
flutter run

# Or run with a specific flavor
flutter run --flavor standard

1. Create a Branch

Create a feature branch from master for your work:

# For new features
git checkout -b feature/your-feature-name

# For bug fixes
git checkout -b fix/issue-description

# For documentation
git checkout -b docs/what-you-are-documenting

2. Make Your Changes

• Keep changes focused and atomic
• Follow the project's architecture and code style (see Architecture)
• Write or update tests where applicable
• Update documentation if you're changing functionality

3. Test Your Changes

# Run linting
flutter analyze

# Run tests
flutter test

# Test the app manually on device/emulator
flutter run

4. Commit Your Changes

Use Conventional Commits format:

# Examples:
git commit -m "feat: add currency search functionality"
git commit -m "fix: resolve crash when converting with empty input"
git commit -m "docs: update README with new features"
git commit -m "refactor: extract currency list into separate widget"

Commit message types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Maintenance tasks
• style: Code style changes (formatting, etc.)

5. Push and Create Pull Request

# Push your branch
git push origin feature/your-feature-name

# Then create a pull request on GitHub

Follow the architecture and code style documented in Architecture. Key points:

Naming Conventions

• PascalCase: Classes and widgets (CurrencyConverter)
• camelCase: Variables and functions (fetchExchangeRates)
• snake_case: File names (currency_converter.dart)
• Prefix 'I': Interfaces (ISettings)

Code Organization

• Group imports: package imports first, then project imports
• Use composition over inheritance for widgets
• Keep widgets small and focused
• Use strong typing with required parameters
• Create dedicated error screens/widgets for different scenarios

Linting

The project uses flutter_lints and riverpod_lint. Ensure your code passes:

flutter analyze

• Include unit tests for business logic and utilities
• Add widget tests for UI components where practical
• Ensure all tests pass before submitting: flutter test
• Test manually on both Android and iOS if possible
• Test both Standard and FOSS build flavors if your changes affect them

Running Tests

# Run all tests
flutter test

# Run a specific test file
flutter test test/widget_test.dart

# Run tests with coverage
flutter test --coverage

Before Submitting

• Ensure flutter analyze passes with no errors
• Ensure flutter test passes
• Update documentation if you've changed functionality
• Test your changes thoroughly
• Rebase on latest master if needed

PR Description

Provide a clear description of your changes:

• What: What does this PR do?
• Why: Why is this change needed?
• How: How did you implement it?
• Testing: How did you test it?
• Screenshots: Include screenshots/recordings for UI changes
• Issues: Link related issues (e.g., "Closes #123")

After Submitting

• Wait for CI checks to pass
• Respond to review feedback promptly
• Make requested changes in new commits (don't force-push)
• Once approved, a maintainer will merge your PR

Use this checklist to verify your environment is ready:

• Flutter SDK installed and flutter doctor passes
• Dependencies installed: flutter pub get
• Code generation running: flutter pub run build_runner build
• Linting passes: flutter analyze
• Tests pass: flutter test
• App runs successfully: flutter run

If you have questions or need help:

• Check the Architecture documentation
• Review existing code for examples
• Open an issue on GitHub
• Ask in your pull request

Please be respectful and constructive in your interactions with other contributors. We aim to create a welcoming and inclusive environment for everyone.