|
| 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 | + |
| 7 | +## Contribution types |
| 8 | + |
| 9 | +### Bug Reports |
| 10 | + - If you find a bug, please first report it using [Github issues]. |
| 11 | + - First check if there is not already an issue for it; duplicated issues will be closed. |
| 12 | + |
| 13 | + |
| 14 | +### Bug Fix |
| 15 | + - If you'd like to submit a fix for a bug, please read the [How To](#how-to-contribute) for how to |
| 16 | + send a Pull Request. |
| 17 | + - Indicate on the open issue that you are working on fixing the bug and the issue will be assigned |
| 18 | + to you. |
| 19 | + - Write `Fixes #xxxx` in your PR text, where xxxx is the issue number (if there is one). |
| 20 | + - Include a test that isolates the bug and verifies that it was fixed. |
| 21 | + |
| 22 | + |
| 23 | +### New Features |
| 24 | + - If you'd like to add a feature to the library that doesn't already exist, feel free to describe |
| 25 | + the feature in a new [GitHub issue]. |
| 26 | + - You can also join us on [Discord] to discuss some initials |
| 27 | + thoughts. |
| 28 | + - If you'd like to implement the new feature, please wait for feedback from the project maintainers |
| 29 | + before spending too much time writing the code. In some cases, enhancements may not align well |
| 30 | + with the project objectives at the time. |
| 31 | + - Implement the code for the new feature and please read the [How To](#how-to-contribute). |
| 32 | + |
| 33 | + |
| 34 | +### Documentation & Miscellaneous |
| 35 | + - If you have suggestions for improvements to the documentation, tutorial or examples (or something |
| 36 | + else), we would love to hear about it. |
| 37 | + - As always first file a [Github issue]. |
| 38 | + - Implement the changes to the documentation, please read the [How To](#how-to-contribute). |
| 39 | + |
| 40 | + |
| 41 | +## How To Contribute |
| 42 | + |
| 43 | +### Requirements |
| 44 | +For a contribution to be accepted: |
| 45 | + |
| 46 | +- Documentation should always be updated or added.* |
| 47 | +- Examples should always be updated or added.* |
| 48 | +- Tests should always be updated or added.* |
| 49 | +- Format the Dart code accordingly with `flutter format`. |
| 50 | +- Your code should pass the analyzer checks `melos run analyze`. |
| 51 | +- Your code should pass all tests `melos run test`. |
| 52 | +- Start your PR title with a [conventional commit] type |
| 53 | + (`feat:`, `fix:` etc). |
| 54 | + |
| 55 | +*When applicable. |
| 56 | + |
| 57 | +If the contribution doesn't meet these criteria, a maintainer will discuss it with you on the issue |
| 58 | +or PR. You can still continue to add more commits to the branch you have sent the Pull Request from |
| 59 | +and it will be automatically reflected in the PR. |
| 60 | + |
| 61 | + |
| 62 | +## Open an issue and fork the repository |
| 63 | + - If it is a bigger change or a new feature, first of all |
| 64 | + [file a bug or feature report][GitHub issues], so that we can discuss what direction to follow. |
| 65 | + - [Fork the project][fork guide] on GitHub. |
| 66 | + - Clone the forked repository to your local development machine |
| 67 | + (e.g. `git clone git@github.com:<YOUR_GITHUB_USER>/tiled.dart.git`). |
| 68 | + |
| 69 | + |
| 70 | +### Environment Setup |
| 71 | +The Dart Tiled library uses [Melos] to manage the project and dependencies. |
| 72 | + |
| 73 | +To install Melos, run the following command from your terminal: |
| 74 | + |
| 75 | +```bash |
| 76 | +flutter pub global activate melos |
| 77 | +``` |
| 78 | + |
| 79 | +Next, at the root of your locally cloned repository bootstrap the projects dependencies: |
| 80 | + |
| 81 | +```bash |
| 82 | +melos bootstrap |
| 83 | +``` |
| 84 | + |
| 85 | +The bootstrap command locally links all dependencies within the project without having to |
| 86 | +provide manual [`dependency_overrides`][pubspec doc]. This allows all |
| 87 | +plugins, examples and tests to build from the local clone project. You should only need to run this |
| 88 | +command once. |
| 89 | + |
| 90 | +> You do not need to run `flutter pub get` once bootstrap has been completed. |
| 91 | +
|
| 92 | + |
| 93 | +### Performing changes |
| 94 | + - Create a new local branch from `main` (e.g. `git checkout -b my-new-feature`) |
| 95 | + - Make your changes (try to split them up with one PR per feature/fix). |
| 96 | + - When committing your changes, make sure that each commit message is clear |
| 97 | + (e.g. `git commit -m 'Take in an optional horizontal offset'`). |
| 98 | + - Push your new branch to your own fork into the same remote branch |
| 99 | + (e.g. `git push origin my-username.my-new-feature`, replace `origin` if you use another remote.) |
| 100 | + |
| 101 | + |
| 102 | +### Breaking changes |
| 103 | + |
| 104 | +When doing breaking changes a deprecation tag should be added when possible and contain a message |
| 105 | +that conveys to the user what which version that the deprecated method/field will be removed in and |
| 106 | +what method they should use instead to perform the task. The version specified should be at least |
| 107 | +two versions after the current one, such that there will be at least one stable release where the |
| 108 | +users get to see the deprecation warning and in the version after that (or a later version) the |
| 109 | +deprecated entity should be removed. |
| 110 | + |
| 111 | +Example (if the current version is v1.3.0): |
| 112 | + |
| 113 | +```dart |
| 114 | +@Deprecated('Will be removed in v1.5.0, use nonDeprecatedFeature() instead') |
| 115 | +void deprecatedFeature() {} |
| 116 | +``` |
| 117 | + |
| 118 | + |
| 119 | +### Open a pull request |
| 120 | + |
| 121 | +Go to the [pull request page of tiled.dart][PRs] and in the top |
| 122 | +of the page it will ask you if you want to open a pull request from your newly created branch. |
| 123 | + |
| 124 | +The title of the pull request should start with a [conventional commit] type. |
| 125 | + |
| 126 | +Examples of such types: |
| 127 | + - `fix:` - patches a bug and is not a new feature. |
| 128 | + - `feat:` - introduces a new feature. |
| 129 | + - `docs:` - updates or adds documentation or examples. |
| 130 | + - `test:` - updates or adds tests. |
| 131 | + - `refactor:` - refactors code but doesn't introduce any changes or additions to the public API. |
| 132 | + |
| 133 | +If you introduce a **breaking change** the conventional commit type MUST end with an exclamation |
| 134 | +mark (e.g. `feat!: Remove the position argument from PositionComponent`). |
| 135 | + |
| 136 | +Examples of PR titles: |
| 137 | + - feat: Hexagon support |
| 138 | + - fix: Avoid infinite loop when parsing tiles |
| 139 | + - docs: Add a hexagon tile example |
| 140 | + - docs: Improve the Mandarin README |
| 141 | + - test: Add infinity test for `Layer` |
| 142 | + - refactor: Optimize the structure of the parsing loop |
| 143 | + |
| 144 | + |
| 145 | +# Maintainers |
| 146 | + |
| 147 | +These instructions are for the maintainers of tiled.dart. |
| 148 | + |
| 149 | + |
| 150 | +## Merging a pull request |
| 151 | + |
| 152 | +When merging a pull request, make sure that the title of the merge commit has the correct |
| 153 | +conventional commit tag and a descriptive title. This is extra important since sometimes the title |
| 154 | +of the PR doesn't reflect what GitHub defaults to for the merge commit title (if the title has been |
| 155 | +changed during the life time of the PR for example). |
| 156 | + |
| 157 | +All the default text should be removed from the commit message and the PR description and the |
| 158 | +instructions from the "Migration instruction" (if the PR is breaking) should be copied into the |
| 159 | +commit message. |
| 160 | + |
| 161 | + |
| 162 | +## Creating a release |
| 163 | + |
| 164 | +There are a few things to think about when doing a release: |
| 165 | + |
| 166 | + - Search through the codebase for `@Deprecated` methods/fields and remove the ones that are marked |
| 167 | + for removal in the version that you are intending to release. |
| 168 | + - Create a PR containing the changes for removing the deprecated entities. |
| 169 | + - Run `melos version -V <package1>:<version> -V <package2>:<version>` for Melos to generate |
| 170 | + `CHANGELOG.md` files. |
| 171 | + - Go through the PRs with breaking changes and add migration documentation to the changelog. |
| 172 | + There should be migration docs on each PR, if they haven't been copied to the commit message. |
| 173 | + - Run `melos publish` to make sure that there aren't any problems with any of the packages and make |
| 174 | + sure that all the versions are correct. |
| 175 | + - Once you are satisfied with the result of the dry run, run `melos publish --no-dry-run` |
| 176 | + - Create a PR containing the updated changelog and `pubspec.yaml` files. |
| 177 | + |
| 178 | + |
| 179 | +[GitHub issue]: https://github.com/flame-engine/tiled.dart/issues/new |
| 180 | +[GitHub issues]: https://github.com/flame-engine/tiled.dart/issues/new |
| 181 | +[PRs]: https://github.com/flame-engine/tiled.dart/pulls |
| 182 | +[fork guide]: https://guides.github.com/activities/forking/#fork |
| 183 | +[Discord]: https://discord.gg/pxrBmy4 |
| 184 | +[Melos]: https://github.com/invertase/melos |
| 185 | +[pubspec doc]: https://dart.dev/tools/pub/pubspec |
| 186 | +[conventional commit]: https://www.conventionalcommits.org |
0 commit comments