|
1 | | -# Way to contribute |
2 | | - |
3 | | -1. Fork the repo and create your branch from `master`. |
4 | | -2. Clone the project to your own machine. |
5 | | -3. Commit changes to your own branch |
6 | | -4. Make sure your code lints. |
7 | | -5. Push your work back up to your fork. |
8 | | -6. Issue that pull request! |
| 1 | +# Contribution Guidelines |
| 2 | + |
| 3 | +**Note:** If these contribution guidelines are not followed your issue or PR might be closed, so |
| 4 | +please read these instructions carefully. |
| 5 | + |
| 6 | +## Contribution types |
| 7 | + |
| 8 | + |
| 9 | +### Bug Reports |
| 10 | + |
| 11 | +- If you find a bug, please first report it using [Github issues]. |
| 12 | + - First check if there is not already an issue for it; duplicated issues will be closed. |
| 13 | + |
| 14 | + |
| 15 | +### Bug Fix |
| 16 | + |
| 17 | +- If you'd like to submit a fix for a bug, please read the [How To](#how-to-contribute) for how to |
| 18 | + send a Pull Request. |
| 19 | +- Indicate on the open issue that you are working on fixing the bug and the issue will be assigned |
| 20 | + to you. |
| 21 | +- Write `Fixes #xxxx` in your PR text, where xxxx is the issue number (if there is one). |
| 22 | +- Include a test that isolates the bug and verifies that it was fixed. |
| 23 | + |
| 24 | + |
| 25 | +### New Features |
| 26 | + |
| 27 | +- If you'd like to add a feature to the library that doesn't already exist, feel free to describe |
| 28 | + the feature in a new [GitHub issue][GitHub issues]. |
| 29 | +- If you'd like to implement the new feature, please wait for feedback from the library maintainers |
| 30 | + before spending too much time writing the code. In some cases, enhancements may not align well |
| 31 | + with the library's future development direction. |
| 32 | +- Implement the code for the new feature and please read the [How To](#how-to-contribute). |
| 33 | + |
| 34 | + |
| 35 | +### Documentation & Miscellaneous |
| 36 | + |
| 37 | +- If you have suggestions for improvements to the documentation, tutorial or examples (or something |
| 38 | + else), we would love to hear about it. |
| 39 | +- As always first file a [Github issue][GitHub issues]. |
| 40 | +- Implement the changes to the documentation, please read the [How To](#how-to-contribute). |
| 41 | + |
| 42 | + |
| 43 | +## How To Contribute |
| 44 | + |
| 45 | + |
| 46 | +### Requirements |
| 47 | + |
| 48 | +For a contribution to be accepted: |
| 49 | + |
| 50 | +- Follow the [Style Guide] when writing the code. |
| 51 | +- Format the code using `flutter format .`. |
| 52 | +- Documentation should always be updated or added (if applicable). |
| 53 | +- Examples should always be updated or added (if applicable). |
| 54 | +- Tests should always be updated or added (if applicable) -- check the [Test writing guide] for |
| 55 | + more details. |
| 56 | +- The PR title should start with a [conventional commit] prefix (`feat:`, `fix:` etc). |
| 57 | + |
| 58 | +If the contribution doesn't meet these criteria, a maintainer will discuss it with you on the issue |
| 59 | +or PR. You can still continue to add more commits to the branch you have sent the Pull Request from |
| 60 | +and it will be automatically reflected in the PR. |
| 61 | + |
| 62 | + |
| 63 | +## Open an issue and fork the repository |
| 64 | + |
| 65 | +- If it is a bigger change or a new feature, first of all |
| 66 | + [file a bug or feature report][GitHub issues], so that we can discuss what direction to follow. |
| 67 | +- [Fork the project][fork guide] on GitHub. |
| 68 | +- Clone the forked repository to your local development machine |
| 69 | + (e.g. `git clone [email protected]:<YOUR_GITHUB_USER>/flutter_credit_card.git`). |
| 70 | + |
| 71 | + |
| 72 | +### Performing changes |
| 73 | + |
| 74 | +- Create a new local branch from `main` (e.g. `git checkout -b my-new-feature`) |
| 75 | +- Make your changes (try to split them up with one PR per feature/fix). |
| 76 | +- When committing your changes, make sure that each commit message is clear |
| 77 | + (e.g. `git commit -m 'Fixes duplicate key found in example'`). |
| 78 | +- Push your new branch to your own fork into the same remote branch |
| 79 | + (e.g. `git push origin my-username.my-new-feature`, replace `origin` if you use another remote.) |
| 80 | + |
| 81 | + |
| 82 | +### Breaking changes |
| 83 | + |
| 84 | +When doing breaking changes a deprecation tag should be added when possible and contain a message |
| 85 | +that conveys to the user what which version that the deprecated method/field will be removed in and |
| 86 | +what method they should use instead to perform the task. The version specified should be at least |
| 87 | +two versions after the current one, such that there will be at least one stable release where the |
| 88 | +users get to see the deprecation warning and in the version after that (or a later version) the |
| 89 | +deprecated entity should be removed. |
| 90 | + |
| 91 | +Example (if the current version is v1.3.0): |
| 92 | + |
| 93 | +```dart |
| 94 | +@Deprecated('Will be removed in v1.5.0, use nonDeprecatedFeature() instead') |
| 95 | +void deprecatedFeature() {} |
| 96 | +``` |
| 97 | + |
| 98 | + |
| 99 | +### Open a pull request |
| 100 | + |
| 101 | +Go to the [pull request page][PRs] and you will asked you if you want to open a pull request from |
| 102 | +your newly created branch right at the top of the page. |
| 103 | + |
| 104 | +The title of the pull request should start with a [conventional commit] type. |
| 105 | +Use [gitmoji] for commit message. |
| 106 | + |
| 107 | +Allowed types are: |
| 108 | + |
| 109 | +- `fix:` -- patches a bug and is not a new feature; |
| 110 | +- `feat:` -- introduces a new feature; |
| 111 | +- `docs:` -- updates or adds documentation or examples; |
| 112 | +- `test:` -- updates or adds tests; |
| 113 | +- `refactor:` -- refactors code but doesn't introduce any changes or additions to the public API; |
| 114 | +- `perf:` -- code change that improves performance; |
| 115 | +- `build:` -- code change that affects the build system or external dependencies; |
| 116 | +- `ci:` -- changes to the CI configuration files and scripts; |
| 117 | +- `chore:` -- other changes that don't modify source or test files; |
| 118 | +- `revert:` -- reverts a previous commit. |
| 119 | + |
| 120 | +If you introduce a **breaking change** the conventional commit type MUST end with an exclamation |
| 121 | +mark (e.g. `feat!: Remove a card provider type`). |
| 122 | + |
| 123 | +Examples of PR titles: |
| 124 | + |
| 125 | +- feat: :sparkles: Add input decoration class |
| 126 | +- fix: :bug: Safe guard adding new Floating events |
| 127 | +- docs: :pencil: Update README.md for preview url |
| 128 | +- test: :rotating_light: Add unit test for `CreditCardForm` |
| 129 | +- refactor: :hammer: Package Structure and Code Improvement |
| 130 | + |
| 131 | + |
| 132 | +## Maintainers |
| 133 | + |
| 134 | +The following instructions are for the maintainers of this package. |
| 135 | + |
| 136 | + |
| 137 | +### Merging a pull request |
| 138 | + |
| 139 | +When merging a pull request, make sure that the title of the merge commit has the correct |
| 140 | +conventional commit tag and a descriptive title. This is extra important since sometimes the title |
| 141 | +of the PR doesn't reflect what GitHub defaults to for the merge commit title (if the title has been |
| 142 | +changed during the life time of the PR for example). |
| 143 | + |
| 144 | +All the default text should be removed from the commit message and the PR description and the |
| 145 | +instructions from the "Migration instruction" (if the PR is breaking) should be copied into the |
| 146 | +commit message. |
| 147 | + |
| 148 | + |
| 149 | +### Creating a release |
| 150 | + |
| 151 | +There are a few things to think about when doing a release: |
| 152 | + |
| 153 | +- Search through the codebase for `@Deprecated` methods/fields and remove the ones that are marked |
| 154 | + for removal in the version that you are intending to release. |
| 155 | +- Create a PR containing the changes for removing the deprecated entities. |
| 156 | +- Go through the PRs with breaking changes and add migration documentation to the changelog. |
| 157 | + There should be migration docs on each PR, if they haven't been copied to the commit message. |
| 158 | +- Create a PR containing the updated changelog and `pubspec.yaml` files. |
| 159 | + |
| 160 | + |
| 161 | +[GitHub issues]: https://github.com/SimformSolutionsPvtLtd/flutter_credit_card/issues/new |
| 162 | +[style guide]: https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo |
| 163 | +[test writing guide]: https://docs.flutter.dev/cookbook/testing/unit/introduction |
| 164 | +[pubspec doc]: https://dart.dev/tools/pub/pubspec |
| 165 | +[conventional commit]: https://www.conventionalcommits.org |
| 166 | +[fork guide]: https://guides.github.com/activities/forking/#fork |
| 167 | +[PRs]: https://github.com/SimformSolutionsPvtLtd/flutter_credit_card/pulls |
| 168 | +[gitmoji]: https://gist.github.com/parmentf/035de27d6ed1dce0b36a |
0 commit comments