diff --git a/.github/ISSUE_TEMPLATE/1_bug.md b/.github/ISSUE_TEMPLATE/1_bug.md new file mode 100644 index 000000000..91d0c9330 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1_bug.md @@ -0,0 +1,46 @@ +--- +name: Bug report. +about: You are creating a Game with Flame but you are noticing some strange behaviour, that it throws an unexpected exception, or that it is not working according to the specifications. +title: '' +labels: 'bug' +assignees: '' + +--- + + + + +# Current bug behaviour + + +# Expected behaviour + + +# Steps to reproduce + + + +# Flutter doctor output + +``` +Output of: flutter doctor -v +``` + +# More environment information + + +# Log information + +``` +Enter log information in this code block +``` + +# More information + + + + +# Problem to solve + + +# Proposal + + +# More information + + + + +# What could be improved + + +# Why should this be improved + + +# Any risks? + + +# More information + + + - -## Description - -Describe your issue here - -## Development environment - -Flame version: - - - -Flutter doctor: - -``` - Include your flutter doctor output here -``` - -## Runtime - -This issue is related to running on which platform? (Select all that apply) - - - [ ] Android :android: - - [ ] iOS :apple: - - [ ] Web :browser: - -## Minimal reproducible code (Required for bugs) - -Include a minimal code that reproduces the problem add it inline using code block markdown, or a link to Github repository: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 572590352..13af88701 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,25 +1,37 @@ -# Description +## Description -Please include a summary of the change. +*Replace this paragraph with a description of what this PR is doing. If you're modifying existing behavior, describe the existing behavior, how this MR is changing it, and what motivated the change. If this is a breaking change, specify explicitly which APIs have been changed* -Fixes # (issue number, if there is one) +## Checklist -## Type of change +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. -Please delete options that are not relevant. +- [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. +- [ ] My PR includes unit or integration tests for *all* changed/updated/fixed behaviors (See [Contributor Guide]). +- [ ] All existing and new tests are passing. +- [ ] I updated/added relevant documentation (doc comments with `///`). +- [ ] The Flame analyzer (`./scripts/analyze.sh`) does not report any problems on my PR. +- [ ] I have added examples for new features in `doc/examples`. +- [ ] I have formatted my code with `./scripts/format.sh`. +- [ ] I read and followed the [Flutter Style Guide]. +- [ ] I have added a description of the change under `[next]` in `CHANGELOG.md`. +- [ ] I am willing to follow-up on review comments in a timely manner. +- [ ] I am happy with the current version of this PR and it is ready to be reviewd + - [ ] I removed the `Draft` status, by clicking on the `Ready for review` button in this PR. -- [ ] Bug fix (non-breaking change which fixes an issue) -- [ ] New feature (non-breaking change which adds functionality) -- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) -- [ ] This change requires a documentation update +## Breaking Change -## Checklist: +Does your PR require Flame users to manually update their apps to accommodate your change? -If something is unclear, please submit the PR anyways and ask about what you thought was unclear. +- [ ] Yes, this is a breaking change (please indicate a breaking change in `CHANGELOG.md`). +- [ ] No, this is *not* a breaking change. -- [ ] This branch is based on the latest `master` -- [ ] I have added an entry under `[next]` in `CHANGELOG.md` -- [ ] I have formatted my code with `flutter format` -- [ ] I have made corresponding changes to the documentation -- [ ] I have added examples for new features in `doc/examples` -- [ ] The continuous integration (CI) is passing +## Related Issues + +*Replace this paragraph with a list of issues related to this PR from the [issue database]. Indicate, which of these issues are resolved or fixed by this PR.* + + +[issue database]: https://github.com/flame-engine/flame/issues +[Contributor Guide]: https://github.com/flame-engine/flame/blob/master/CONTRIBUTING.md +[Flutter Style Guide]: https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo +[pub versioning philosophy]: https://www.dartlang.org/tools/pub/versioning diff --git a/.github/workflows/cicd.yml b/.github/workflows/cicd.yml new file mode 100644 index 000000000..8bbbf7676 --- /dev/null +++ b/.github/workflows/cicd.yml @@ -0,0 +1,64 @@ +name: cicd + +on: + push: + branches: + - master + pull_request: + types: [opened, reopened, synchronize] + +jobs: + # BEGIN LINTING STAGE + dartdoc: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-java@v1 + with: + java-version: '12.x' + - uses: subosito/flutter-action@v1 + with: + channel: 'beta' + - run: flutter pub get + - run: ./scripts/dartdoc.sh + + format: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-java@v1 + with: + java-version: '12.x' + - uses: subosito/flutter-action@v1 + with: + channel: 'beta' + - run: ./scripts/format.sh + + analyze: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-java@v1 + with: + java-version: '12.x' + - uses: subosito/flutter-action@v1 + with: + channel: 'beta' + - run: ./scripts/analyze.sh + # END LINTING STAGE + + # BEGIN TESTING STAGE + test: + needs: [dartdoc, format, analyze] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: actions/setup-java@v1 + with: + java-version: '12.x' + - uses: subosito/flutter-action@v1 + with: + channel: 'beta' + - run: flutter pub get + - run: flutter test + # END TESTING STAGE diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml deleted file mode 100644 index 7ac01bda7..000000000 --- a/.github/workflows/test.yml +++ /dev/null @@ -1,27 +0,0 @@ -name: Test - -on: - push: - branches: - - master - - master-v0.x - pull_request: - types: [opened, reopened, synchronize] - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v1 - - uses: actions/setup-java@v1 - with: - java-version: '12.x' - - uses: subosito/flutter-action@v1 - with: - channel: 'beta' - - run: git clean -xffd # https://github.com/dart-lang/sdk/issues/39792 - - run: flutter --version - - run: flutter pub get - - run: ./scripts/lint.sh - - run: flutter test diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..7060250d4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,56 @@ +# Contributing Guidelines +If you're interested in contributing to this project, here are a few ways to do so: + +**Note:** If these contributing guidelines are not followed we will close the issue or PR, please read these instructions carefully. + +## Bug fixes +* If you find a bug, please first report it using [Github issues](https://github.com/flame-engine/flame/issues/new). + * First check if there is not already an issue for it; duplicated issues will be closed. +* Issues that have already been identified as a bug will be labelled "bug". +* If you'd like to submit a fix for a bug, send a [Pull Request](https://guides.github.com/activities/forking/#making-a-pull-request) from your own fork, also read the [How To](#how-to) and [Development Guidelines](#development-guidelines). +* Include a test that isolates the bug and verifies that it was fixed. +* Also update the examples and documentation if necessary. + +## 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 issues](https://github.com/flame-engine/flame/issues/new). + * You can also join us on [Discord](https://discord.gg/pxrBmy4) to discuss some initials thoughts. +* Issues that have been identified as a feature request will be labelled "enchanment". +* 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. +* Implement your code and please read the [How To](#how-to) and [Development Guidelines](#development-guidelines). +* Also update the examples and documentation where needed. + +## Documentation & Miscellaneous +* If you think the documentation could be clearer or an example should be added, or you have an alternative implementation of something that may have more advantages, we would love to hear it. +* As always first file a report in a [Github issues](https://github.com/flame-engine/flame/issues/new). +* Issues that have been identified as a documentation change will be labelled "documentation". +* Implement the changes to the documentation, please read the [How To](#how-to) and [Development Guidelines](#development-guidelines). + +# Requirements +For a contribution to be accepted: + +* Take note of the [Development Guidelines](#development-guidelines) +* Code must follow existing styling conventions +* Commit message should start with a [issue number](#how-to) and should also be descriptive. + +If the contribution doesn't meet these criteria, a maintainer will discuss it with you on the issue. You can still continue to add more commits to the branch you have sent the Pull Request from. + +# How To Contribute +* First of all [file an bug or feature report](https://github.com/flame-engine/flame/issues/new) on this repository. +* [Fork the project](https://guides.github.com/activities/forking/#fork) on Github +* Clone the forked repository to your local development machine (e.g. `git clone https://github.com//flame.git`) +* Run `flutter pub get` in the cloned repository to get all the dependencies +* Create a new local branch based on issue number from first step (e.g. `git checkout -b 12-new-feature`) +* Make your changes +* When committing your changes, make sure to start the commit message with `#` (e.g. `git commit -m '#12 - New Feature added'`) +* Push your new branch to your own fork into the same remote branch (e.g. `git push origin 12-new-feature`) +* On Github goto the [pull request page](https://guides.github.com/activities/forking/#making-a-pull-request) on your own fork and create a merge request to this reposistory + +# Development Guidelines +* Documentation should be updated. +* Examples should be updated. +* Format the Dart code accordingly. +* Note the [`analysis_options.yaml`](https://github.com/flame-engine/flame/blob/master/analysis_options.yaml) and write code as stated in this file + +# Test generating of `dartdoc` +* Run the `./scripts/dartdoc.sh` script to generate the Dart documentation. +* Output will be placed into `doc/api/`. diff --git a/pubspec.yaml b/pubspec.yaml index 668a63b23..d5d8e1f1e 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -15,6 +15,7 @@ dev_dependencies: sdk: flutter test: ^1.9.4 dart_code_metrics: ^2.4.0 + dartdoc: ^0.39.0 environment: sdk: ">=2.7.0 <3.0.0" diff --git a/scripts/analyze.sh b/scripts/analyze.sh new file mode 100755 index 000000000..16a271a81 --- /dev/null +++ b/scripts/analyze.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash + +flutter pub get + +# We need to run pubget on all the examples +for f in $(find doc/examples -name 'pubspec.yaml'); do + d=$(dirname $f) + cd $d + flutter pub get + cd - > /dev/null +done + +cd . +flutter pub get +result=$(flutter pub run dart_code_metrics:metrics .) +if [ "$result" != "" ]; then + echo "flutter dart code metrics issues: $1" + echo "$result" + exit 1 +fi +result=$(flutter analyze .) +if ! echo "$result" | grep -q "No issues found!"; then + echo "$result" + echo "flutter analyze issue: $1" +fi + +exit 0 diff --git a/scripts/build.sh b/scripts/build.sh index 377a68ae7..b7863d6ed 100755 --- a/scripts/build.sh +++ b/scripts/build.sh @@ -1,4 +1,4 @@ -#!/bin/bash -e +#!/usr/bin/env bash # run this first time: # flutter update-packages diff --git a/scripts/dartdoc.sh b/scripts/dartdoc.sh new file mode 100755 index 000000000..79f9f1fe2 --- /dev/null +++ b/scripts/dartdoc.sh @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +flutter pub run dartdoc --no-auto-include-dependencies --quiet diff --git a/scripts/format.sh b/scripts/format.sh new file mode 100755 index 000000000..e53a8f30d --- /dev/null +++ b/scripts/format.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash + +FORMAT_ISSUES=$(flutter format --set-exit-if-changed -n .) +if [ $? -eq 1 ]; then + echo "flutter format issues on" + echo $FORMAT_ISSUES + exit 1 +fi \ No newline at end of file diff --git a/scripts/gen-doc.sh b/scripts/gen-doc.sh deleted file mode 100755 index a982ddecd..000000000 --- a/scripts/gen-doc.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/bin/bash -e - -dartdoc diff --git a/scripts/lint.sh b/scripts/lint.sh index 045d7634d..e8e53ccbb 100755 --- a/scripts/lint.sh +++ b/scripts/lint.sh @@ -1,35 +1,14 @@ #!/usr/bin/env bash -FORMAT_ISSUES=$(flutter format --set-exit-if-changed -n .) + +./scripts/format.sh if [ $? -eq 1 ]; then - echo "flutter format issues on" - echo $FORMAT_ISSUES + echo "Formatting failed!" + exit 1 +fi +./scripts/analyze.sh +if [ $? -eq 1 ]; then + echo "Analyzing failed!" exit 1 fi -flutter pub get - -# We need to run pubget on all the examples -for f in $(find doc/examples -name 'pubspec.yaml'); do - d=$(dirname $f) - cd $d - flutter pub get - cd - > /dev/null -done - -cd . -flutter pub get -result=$(flutter pub run dart_code_metrics:metrics .) -if [ "$result" != "" ]; then - echo "flutter dart code metrics issues: $1" - echo "$result" - exit 1 -fi -result=$(flutter analyze .) -if ! echo "$result" | grep -q "No issues found!"; then - echo "$result" - echo "flutter analyze issue: $1" - exit 1 -fi - -echo "success" -exit 0 +echo "Succesfully linted!" \ No newline at end of file