diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eeb25657..494c697e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,27 @@ # Contributing -The contributions are more than welcome!
-This project will be better with the open-source community help +First of all, we would like to thank you for your time and efforts on this project, we appreciate it -You can check the [Todo](./doc/todo.md) list if you want to +You can see tutorials online on how to contribute to any open source project, it's a simple process, and you can do it even if you are not Git expert, simply start by forking the repository, clone it, creating a new branch, make your changes and commit them, then push the branch to your fork, and you will get link to send a PR to the upstream repository -There are no guidelines for now. -This page will be updated in the future. +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 + +You can also check the [Todo](./doc/todo.md) list or the issues if you want to + +## Requirements + +- [Flutter SDK](https://docs.flutter.dev/get-started/install) which can be installed by following the instructions the provided link, also make sure to add it to your path so `flutter --version` and `dart --version` work +- [Intellij IDEA Community Edition](https://www.jetbrains.com/idea/download/) or [Android Studio](https://developer.android.com/studio) (with Dart and Flutter plugins) or use [VS Code](https://code.visualstudio.com/) (with Dart and flutter extensions) + + +## Test your changes ๐Ÿงช + +Make sure you have the [Requirement](#requirements) installed and configured correctly + +To test your changes: + +1. Go to the [Example project](./example/) in [main.dart](./example/lib/main.dart) and run the project either by using your IDE or `flutter run` +2. Make sure to read the [Development Notes](./doc/development_notes.md) if you made certain changes or [Translations Page](./doc/translation.md) if you made changes to the translations of the package ## Steps to contributing @@ -19,19 +34,15 @@ You will need a GitHub account as well as Git installed and configured with your git remote add upstream git@github.com:singerdmx/flutter-quill.git ``` 4. Open the project with your favorite IDE, usually, we prefer to use Jetbrains IDEs, but since [VS Code](https://code.visualstudio.com) is more used and has more support for Dart, then we suggest using it if you want to. -5. Create a new git branch and switch to it using: - - ``` - git checkout -b your-branch-name - ``` - The `your-branch-name` is your choice +5. Create a new git branch and switch to it using `git checkout -b` 6. Make your changes -7. If you are working on changes that depend on different libraries in the same repo, then in that directory copy `pubspec_overrides.yaml.disabled` which exists in all the libraries (`flutter_quill_test` and `flutter_quill_extensions` etc...) +7. If you are working on changes that depend on different libraries in the same repo, then in that directory copy `pubspec_overrides.yaml.disabled` which exists in all the packages (`flutter_quill_test` and `flutter_quill_extensions` etc...) to `pubspec_overrides.yaml` which will be ignored by `.gitignore` and will be used by dart pub to override the libraries ``` cp pubspec_overrides.yaml.disabled pubspec_overrides.yaml ``` or save some time with the following script: + ``` ./scripts/enable_local_dev.sh ``` @@ -44,7 +55,7 @@ to `pubspec_overrides.yaml` which will be ignored by `.gitignore` and will be us ``` git add . git commit -m "Your commit message" - git push origin your-branch-name + git push origin ``` this will push the new branch to your forked repository @@ -52,14 +63,58 @@ to `pubspec_overrides.yaml` which will be ignored by `.gitignore` and will be us forked repository. You will find an option to send the pull request, you can also open the [Pull Requests](https://github.com/singerdmx/flutter-quill) tab and send new pull request -12. Please wait for the review, and we might ask you to make more changes, then run: +12. Now, wait for the review, and we might ask you to make more changes, then run: ``` git add . git commit -m "Your new commit message" git push origin your-branch-name ``` -Thank you for your time and efforts in this open-source community project!! +Thank you for your time and efforts in open-source projects!! + +## 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](https://dart.dev/tools/linter-rules) 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**: + + Try to follow semantic versioning for releases (https://semver.org/) when possible. + Clearly document release notes and changes for each version. + Please notice for now we might introduce breaking changes in non-major version but will always provide migration + guide in each release info and in [Migration guide](./doc/migration.md) +7. **Consistency**: + + Adhere to a consistent coding style throughout the project for improves 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 -Please read the [Development Notes](./doc/development_notes.md) as they are important while development \ No newline at end of file + +Please read the [Development Notes](./doc/development_notes.md) as they might be important while development \ No newline at end of file