Skip to content

Latest commit

 

History

History
101 lines (75 loc) · 5.26 KB

CONTRIBUTING.md

File metadata and controls

101 lines (75 loc) · 5.26 KB
Raw

🌱 Contributing

First, we would like to thank you for your time and efforts on this project, we appreciate it.

Important

At this time, we prioritize bug fixes and code quality improvements over new features. Please refrain from submitting large changes to add new features, as they might not be merged, and exceptions may made. We encourage you to create an issue or reach out beforehand, explaining your proposed changes and their rationale for a higher chance of acceptance. Thank you!

If you don't have anything specific in mind to improve or fix, you can take a look at the issues tab or take a look at the todos of the project, they all start with TODO: so you can search in your IDE or use the todos tab in the IDE.

Make sure to not edit the CHANGELOG.md or the version in pubspec.yaml for any of the packages, CI will automate this process.

📋 Development Prerequisites

🧪 Test your changes

Make sure you have the Requirement installed and configured correctly

To test your changes:

  1. Go to the Example project in main.dart and run the project either by using your IDE or flutter run
  2. Make sure to read the Development Notes if you made certain changes or Translations Page if you made changes to the translations of the package

Guidelines 📝

  1. Code Style and Formatting:

    Adhere to the Dart Coding Conventions (https://dart.dev/effective-dart). Use consistent naming conventions for variables, functions, classes, etc. Follow a consistent code formatting style throughout the project.

    We use Dart lints to make the process easier.

  2. Documentation:

    Document public APIs using Dart comments (https://dart.dev/effective-dart/documentation). Provide comprehensive documentation for any complex algorithms, data structures, or significant functionality. Write clear and concise commit messages and pull request descriptions.

  3. Performance:

    Write efficient code and avoid unnecessary overhead. Profile the application for performance bottlenecks and optimize critical sections if needed.

  4. Bundle size:

    Try to make the package size as less as possible but as much as needed

  5. Code Review:

    Encourage code reviews for all changes to maintain code quality and catch potential issues early. Use pull requests and code reviews to discuss proposed changes and improvements.

  6. Versioning and Releases:

    Follow semantic versioning for releases (https://semver.org/). Clearly document release notes and changes for each version.

    For now, we might introduce breaking changes in a non-major version but will always provide a migration guide in each release info.

  7. Consistency:

    Adhere to a consistent coding style throughout the project for improvement readability and maintainability

  8. Meaningful Names:

    Use descriptive variable, class, and function names that clearly convey their purpose.

  9. Testing:

    Try to write tests (Widget or Unit tests or other types or tests) when possible

📝 Development Notes

  • When updating the translations or localizations in the app, please take a look at the Translation page as it has important notes to work. If you also add a feature that adds new localizations, then you need it to the instructions of it in order for the translations to take effect

  • We use the same package version and CHANGELOG.md for all the packages, for more details, the process is automated. We have a script that will do the following:

    1. Generate the CHANGELOG.md files by CHANGELOG_JSON.json (source of data) and then paste them into all the packages we have (overwrite), you don't need to manually change/update any of the mentioned files above, once a new GitHub release published, the CI will take the release notes from the release, pass the info to the script, the release notes can be auto-generated by GitHub using a button, a descriptive PRs title would help but you don't have to since we can change it at any time.
    2. The script require the new version as an argument, you don't need to run the script manually, when a maintainer create a new tag and publish a new GitHub release, the publishing workflow will extract the new version from the tag name, run the script (pass the extracted version as an argument), commit the changes and push them into the repository, the script will update the version property for all the packages so the flutter pub publish will use the new version for each package correctly.

    the script will be used the CI and no need to run it manually