docs: Added Style Guide and Test Writing Guide (#1897)

The Style Guide moved into the Documentation site for better visibility. Removed lots of discussion around topics that are already enforced by the formatter/linter. Added new advice regarding a variety of topics.

The Test Writing Guide discusses how to write tests for Flame, and what kinds of tests are available.

.github/pull_request_template.md

@@ -1,45 +1,49 @@
 # Description
-
-<!-- Provide a description of what this PR is doing. 
+<!--
+Provide a description of what this PR is doing.
 If you're modifying existing behavior, describe the existing behavior, how this PR is changing it,
-and what motivated the change. If this is a breaking change, specify explicitly which APIs have been
-changed. -->
+and what motivated the change. If this is a breaking change, specify explicitly which APIs were
+changed.
+-->
 
-## Checklist
 
-<!-- Before you create this PR confirm that it meets all requirements listed below by checking the
-relevant checkboxes (`[x]`). This will ensure a smooth and quick review process. -->
+## Checklist
+<!--
+Before you create this PR confirm that it meets all requirements listed below by checking the
+relevant checkboxes with `[x]`. If some checkbox is not applicable, mark it as `[-]`.
+-->
 
 - [ ] The title of my PR starts with a [Conventional Commit] prefix (`fix:`, `feat:`, `docs:` etc).
-- [ ] I have read the [Contributor Guide] and followed the process outlined for submitting PRs.
+- [ ] I have followed the [Contributor Guide] when preparing my PR.
 - [ ] I have updated/added tests for ALL new/updated/fixed functionality.
 - [ ] I have updated/added relevant documentation in `docs` and added dartdoc comments with `///`.
-- [ ] I have updated/added relevant examples in `examples`.
+- [ ] I have updated/added relevant examples in `examples` or `docs`.
 
-## Breaking Change
 
-<!-- Does your PR require Flame users to manually update their apps to accommodate your change? 
+## Breaking Change?
+<!--
+Would your PR require Flame users to update their apps following your change?
 
-If the PR is a breaking change this should be indicated with suffix "!" 
-(for example, `feat!:`, `fix!:`). See [Conventional Commit] for details.
--->
-
-- [ ] Yes, this is a breaking change.
-- [ ] No, this is *not* a breaking change.
+If yes, then the title of the PR should include "!" (for example, `feat!:`, `fix!:`). See
+[Conventional Commit] for details. Also, for a breaking PR uncomment and fill in the "Migration
+instructions" section below.
 
-<!-- ### Migration instructions
+### Migration instructions
 
 If the PR is breaking, uncomment this header and add instructions for how to migrate from the
 currently released version to the new proposed way.
 -->
 
-## Related Issues
+- [ ] Yes, this PR is a breaking change.
+- [ ] No, this PR is not a breaking change.
 
-<!-- Provide a list of issues related to this PR from the [issue database].
-Indicate which of these issues are resolved or fixed by this PR, i.e. Fixes #xxxx* !-->
+
+## Related Issues
+<!--
+Indicate which issues this PR resolves, if any. For example:
+Closes #1234
+!-->
 
 <!-- Links -->
-[issue database]: https://github.com/flame-engine/flame/issues
 [Contributor Guide]: https://github.com/flame-engine/flame/blob/main/CONTRIBUTING.md
-[Flame Style Guide]: https://github.com/flame-engine/flame/blob/main/STYLEGUIDE.md
 [Conventional Commit]: https://conventionalcommits.org

CONTRIBUTING.md

@@ -23,11 +23,10 @@ please read these instructions carefully.
 ### New Features
  - If you'd like to add a feature to the library that doesn't already exist, feel free to describe
    the feature in a new [GitHub issue].
-   - You can also join us on [Discord] to discuss some initials
-   thoughts.
+   - You can also join us on [Discord] to discuss some initials thoughts.
  - If you'd like to implement the new feature, please wait for feedback from the project maintainers
    before spending too much time writing the code. In some cases, enhancements may not align well
-   with the project objectives at the time.
+   with the project future development direction.
  - Implement the code for the new feature and please read the [How To](#how-to-contribute).
 
 
@@ -41,25 +40,26 @@ please read these instructions carefully.
 ## How To Contribute
 
 ### Requirements
-For a contribution to be accepted:
 
-- Documentation should always be updated or added.*
-- Examples should always be updated or added.*
-- Tests should always be updated or added.*
-- Format the Dart code accordingly with `flutter format`.
-- Your code should pass the analyzer checks `melos run analyze`.
-- Your code should pass all tests `melos run test`.
-- Start your PR title with a [conventional commit] type
-  (`feat:`, `fix:` etc).
+For a contribution to be accepted:
 
-*When applicable.
+- Follow the [Style Guide] when writing the code;
+- Format the code using `flutter format .`;
+- Lint the code with `melos run analyze`;
+- Check that all tests pass: `melos run test`;
+- Documentation should always be updated or added (if applicable);
+- Examples should always be updated or added (if applicable);
+- Tests should always be updated or added (if applicable) -- check the [Test writing guide] for
+  more details;
+- The PR title should start with a [conventional commit] prefix (`feat:`, `fix:` etc).
 
 If the contribution doesn't meet these criteria, a maintainer will discuss it with you on the issue
 or PR. You can still continue to add more commits to the branch you have sent the Pull Request from
 and it will be automatically reflected in the PR.
 
 
 ## Open an issue and fork the repository
+
  - If it is a bigger change or a new feature, first of all
    [file a bug or feature report][GitHub issues], so that we can discuss what direction to follow.
  - [Fork the project][fork guide] on GitHub.
@@ -68,9 +68,9 @@ and it will be automatically reflected in the PR.
 
 
 ### Environment Setup
-Flame uses [Melos] to manage the project and dependencies.
 
-To install Melos, run the following command from your terminal:
+Flame uses [Melos] to manage the project and dependencies. To install Melos, run the following
+command from your terminal:
 
 ```bash
 flutter pub global activate melos
@@ -91,6 +91,7 @@ command once.
 
 
 ### Performing changes
+
  - Create a new local branch from `main` (e.g. `git checkout -b my-new-feature`)
  - Make your changes (try to split them up with one PR per feature/fix).
  - When committing your changes, make sure that each commit message is clear
@@ -117,17 +118,23 @@ void deprecatedFeature() {}
 
 
 ### Open a pull request
+
 Go to the [pull request page of Flame][PRs] and in the top
 of the page it will ask you if you want to open a pull request from your newly created branch.
 
 The title of the pull request should start with a [conventional commit] type.
 
-Examples of such types:
- - `fix:` - patches a bug and is not a new feature.
- - `feat:` - introduces a new feature.
- - `docs:` - updates or adds documentation or examples.
- - `test:` - updates or adds tests.
- - `refactor:` - refactors code but doesn't introduce any changes or additions to the public API.
+Allowed types are:
+ - `fix:` -- patches a bug and is not a new feature;
+ - `feat:` -- introduces a new feature;
+ - `docs:` -- updates or adds documentation or examples;
+ - `test:` -- updates or adds tests;
+ - `refactor:` -- refactors code but doesn't introduce any changes or additions to the public API;
+ - `perf:` -- code change that improves performance;
+ - `build:` -- code change that affects the build system or external dependencies;
+ - `ci:` -- changes to the CI configuration files and scripts;
+ - `chore:` -- other changes that don't modify source or test files;
+ - `revert:` -- reverts a previous commit.
 
 If you introduce a **breaking change** the conventional commit type MUST end with an exclamation
 mark (e.g. `feat!: Remove the position argument from PositionComponent`).
@@ -183,3 +190,5 @@ There are a few things to think about when doing a release:
 [Melos]: https://github.com/invertase/melos
 [pubspec doc]: https://dart.dev/tools/pub/pubspec
 [conventional commit]: https://www.conventionalcommits.org
+[style guide]: https://docs.flame-engine.org/main/development/style_guide.md
+[test writing guide]: https://docs.flame-engine.org/main/development/testing_guide.md

doc/development/development.md

@@ -1,5 +1,9 @@
 # Development
 
 ```{toctree}
-Documentation       <documentation.md>
+:maxdepth: 2
+
+Documentation  <documentation.md>
+Style Guide    <style_guide.md>
+Tests Guide    <testing_guide.md>
 ```