com.nahnah.florid/CONTRIBUTING.md

Contributing to Florid

Thank you for your interest in contributing to Florid! We welcome contributions from everyone. This guide will help you get started.

Table of Contents

• Code of Conduct
• How Can I Contribute?
  • Reporting Bugs
  • Suggesting Features
  • Contributing Code
  • Contributing Translations
• Development Setup
• Pull Request Process
• Style Guidelines
• Localization Guidelines

Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment for everyone.

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:

• Clear title and description
• Steps to reproduce the issue
• Expected behavior vs actual behavior
• Screenshots if applicable
• Device information (Android version, device model)
• App version you're using

Suggesting Features

Feature suggestions are welcome! Please:

• Check existing feature requests first
• Describe the feature in detail
• Explain the use case and why it would be valuable
• Consider implementation complexity

Contributing Code

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly
5. Commit with clear messages (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Contributing Translations

We use easy_localization for internationalization. Contributing translations is easy and highly appreciated!

Adding a New Language

1. Create a translation file:

   • Navigate to assets/translations/
   • Create a new JSON file named with the language code (e.g., fr.json for French, de.json for German)
   • Copy the structure from en.json

2. Translate all keys:

   {
     "app_name": "Florid",
     "welcome": "Your translation here",
     "search": "Your translation here",
     ...
   }
   

3. Update main.dart: Add your locale to the supported locales list:

   EasyLocalization(
     supportedLocales: const [
       Locale('en'),
       Locale('es'),
       Locale('fr'),  // Your new language
     ],
     // ...
   )
   

4. Test your translations:

   • Change your device language to the new language
   • Launch the app and verify all strings appear correctly
   • Check that text fits in UI elements (some languages use longer words)

Improving Existing Translations

1. Open the relevant JSON file in assets/translations/
2. Update the translation values
3. Ensure translations are:
   • Accurate and contextually appropriate
   • Natural in the target language
   • Consistent with app terminology
4. Test the changes in the app

Translation Guidelines

• Keep keys unchanged - Only modify the values, never the keys
• Maintain consistency - Use the same terms throughout for repeated concepts
• Consider context - Some words have different meanings in different contexts
• Test thoroughly - Verify translations in the actual UI
• Be concise - Mobile UIs have limited space
• Use native conventions - Follow target language conventions for dates, numbers, etc.

See LOCALIZATION.md for detailed localization documentation.

Development Setup

Prerequisites

• Flutter SDK (3.38.7 or higher)
• Dart SDK (3.9.2 or higher)
• Android Studio or VS Code with Flutter extensions
• Android device or emulator for testing

Setup Steps

1. Clone the repository:

   git clone https://github.com/yourusername/florid.git
   cd florid
   

2. Install dependencies:

   flutter pub get
   

3. Run the app:

   flutter run
   

Project Structure

lib/
├── models/          # Data models
├── providers/       # State management (Provider)
├── screens/         # UI screens
├── services/        # API and business logic
├── themes/          # App themes
├── utils/           # Utility functions
├── widgets/         # Reusable widgets
└── main.dart        # App entry point

assets/
└── translations/    # Translation JSON files

Pull Request Process

1. Update documentation if you've made changes to APIs or added features
2. Add/update tests for new functionality
3. Follow the style guidelines below
4. Ensure the app builds without errors
5. Test on a real device when possible
6. Update CHANGELOG.md with notable changes
7. Link any related issues in the PR description

PR Checklist

• Code follows the project style guidelines
• Self-review of code completed
• Comments added for complex logic
• Documentation updated if needed
• No new warnings generated
• Translations added/updated if UI text changed
• Tested on Android device/emulator

Style Guidelines

Dart Code Style

• Follow Effective Dart guidelines
• Use flutter analyze to check for issues
• Format code with dart format .
• Maximum line length: 80 characters (flexible for readability)

Widget Organization

class MyWidget extends StatelessWidget {
  // 1. Final fields
  final String title;

  // 2. Constructor
  const MyWidget({super.key, required this.title});

  // 3. Build method
  @override
  Widget build(BuildContext context) {
    // ...
  }

  // 4. Helper methods
  void _helperMethod() {
    // ...
  }
}

Naming Conventions

• Classes: PascalCase (e.g., AppDetailsScreen)
• Files: snake_case (e.g., app_details_screen.dart)
• Variables/Functions: camelCase (e.g., downloadApp)
• Constants: camelCase (e.g., maxRetries)
• Private members: prefix with _ (e.g., _privateMethod)

Comments

• Use /// for public API documentation
• Use // for inline comments
• Explain why, not what (code should be self-documenting)

// Good
/// Fetches app details from the repository.
/// Returns null if the app is not found or network error occurs.
Future<FDroidApp?> fetchAppDetails(String packageName) async { ... }

// Bad
// This function gets the app
Future<FDroidApp?> fetchAppDetails(String packageName) async { ... }

UI/UX Guidelines

• Responsive Design: Test on different screen sizes
• Accessibility: Use semantic labels and ensure good contrast
• Performance: Avoid unnecessary rebuilds, use const constructors
• Material Design: Follow Material 3 guidelines
• Animations: Keep animations smooth and purposeful (avoid excessive animation)

Localization Guidelines

Adding New Strings

When adding new UI text:

1. Never hardcode strings in UI code

2. Add to all translation files (at minimum en.json and es.json)

3. Use descriptive keys with underscores:

   {
     "error_network_title": "Network Error",
     "error_network_message": "Please check your internet connection",
     "button_retry": "Retry"
   }
   

4. Use the string in code:

   Text('error_network_title'.tr())
   

Translation Key Naming

Follow this pattern: [category]_[context]_[element]

Examples:

• error_network_title
• settings_theme_dark
• dialog_delete_confirm
• button_download
• label_version_name

Context for Translators

When adding strings that might be ambiguous, add a comment in the PR:

Added "bank" key - refers to river bank, not financial institution

Questions?

If you have questions or need help:

• Open an issue with the question label
• Check existing issues and discussions
• Review the documentation in the repository

License

By contributing to Florid, you agree that your contributions will be licensed under the same license as the project.

---

Thank you for contributing to Florid! 🎉