From 58e262f55c84733b14fb70963d5eb63f67611be6 Mon Sep 17 00:00:00 2001 From: Felix Angelov Date: Tue, 12 Apr 2022 16:14:32 -0500 Subject: [PATCH] docs: README enhancements (#23) --- README.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++--- src/README.md | 2 +- 2 files changed, 86 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 5448f41..7b298c1 100644 --- a/README.md +++ b/README.md @@ -5,13 +5,92 @@ Developed with ๐Ÿ’™ by [Very Good Ventures][very_good_ventures_link] ๐Ÿฆ„ +[![my_plugin][build_status_badge]][build_status_link] +![coverage][coverage_badge] [![style: very good analysis][very_good_analysis_badge]][very_good_analysis_link] [![License: MIT][license_badge]][license_link] A Very Good Flutter Plugin created by the [Very Good Ventures Team][very_good_ventures_link]. -Generated by the [Very Good CLI][very_good_cli_link] ๐Ÿค– +## Getting Started ๐Ÿš€ +**โ— In order to start using Very Good Flutter Plugin you must have the [Flutter SDK][flutter_install_link] installed on your machine.** + +### Running the Example โš™๏ธ + +The `src` directory contains the main `my_plugin` package along with the platform interface and the platform-specific implementations. + +You can run the example via: + +```sh +cd src/my_plugin/example +flutter run +``` + +The plugin supports the following platforms: + +- โœ… Android +- โœ… iOS +- โœ… Linux +- โœ… MacOS +- โœ… Web +- โœ… Windows + +### Generating a Custom Plugin ๐Ÿ“ฆ + +This repository powers the `flutter_plugin` template exposed via [Very Good CLI][very_good_cli_link]. + +If you have not previously installed Very Good CLI, you can install it via: + +```sh +dart pub global activate very_good_cli +``` + +A custom plugin can be generated via the `create` command: + +```sh +very_good create my_plugin -t flutter_plugin +``` + +A custom description and org name can be also be provided via: + +```sh +very_good create my_plugin -t flutter_plugin --desc "My custom description" --org-name com.example.my_plugin +``` + +By default, the generated plugin supports all platforms specified above. To disable support for specific platforms use the platform flags: + +```sh +# Exclude Windows and Linux support +very_good create my_plugin -t flutter_plugin --windows false --linux false +``` + +## Testing ๐Ÿงช + +Very Good Flutter Plugin ships with 100% code coverage. To learn more about why we believe 100% code coverage is important and other testing best practices [read our guide to Flutter testing][very_good_testing_blog_link]. + +### Running Tests ๐Ÿง‘โ€๐Ÿ”ฌ + +Each platform implementation includes tests which can be run via: + +```sh +flutter test +``` + +## Continuous Integration ๐Ÿค– + +Very Good Flutter Plugin comes with a built-in [GitHub Actions workflow][github_actions_link] but you can also add your preferred CI/CD solution. + +Out of the box, on each pull request and push, the CI `formats`, `lints`, and `tests` the code using [Very Good Workflows][very_good_workflows_link]. This ensures the code remains consistent and behaves correctly as you add functionality or make changes. The project uses [Very Good Analysis][very_good_analysis_link] for a strict set of analysis options used by our team. Code coverage is enforced using the [Very Good Coverage GitHub Action][very_good_coverage_link]. + +In addition, there are E2E tests as part of the `my_plugin` workflow to ensure that the plugin correctly integrates with the host application on each platform. + +[build_status_badge]: https://github.com/VeryGoodOpenSource/very_good_flutter_plugin/actions/workflows/my_plugin.yaml/badge.svg +[build_status_link]: https://github.com/VeryGoodOpenSource/very_good_flutter_plugin/actions/workflows/my_plugin.yaml +[coverage_badge]: src/my_plugin/coverage_badge.svg +[flutter_install_link]: https://flutter.dev/docs/get-started/install +[github_actions_link]: https://docs.github.com/en/actions/learn-github-actions +[github_workflow_link]: https://docs.github.com/en/enterprise-cloud@latest/actions/using-workflows [license_badge]: https://img.shields.io/badge/license-MIT-blue.svg [license_link]: https://opensource.org/licenses/MIT [logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only @@ -19,6 +98,8 @@ Generated by the [Very Good CLI][very_good_cli_link] ๐Ÿค– [very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg [very_good_analysis_link]: https://pub.dev/packages/very_good_analysis [very_good_cli_link]: https://github.com/VeryGoodOpenSource/very_good_cli -[very_good_ventures_link]: https://verygood.ventures/?utm_source=github&utm_medium=banner&utm_campaign=core -[very_good_ventures_link_dark]: https://verygood.ventures/?utm_source=github&utm_medium=banner&utm_campaign=core#gh-dark-mode-only -[very_good_ventures_link_light]: https://verygood.ventures/?utm_source=github&utm_medium=banner&utm_campaign=core#gh-light-mode-only +[very_good_workflows_link]: https://github.com/verygoodopensource/very_good_workflows +[very_good_testing_blog_link]: https://verygood.ventures/blog/guide-to-flutter-testing +[very_good_ventures_link]: https://verygood.ventures +[very_good_ventures_link_dark]: https://verygood.ventures#gh-dark-mode-only +[very_good_ventures_link_light]: https://verygood.ventures#gh-light-mode-only diff --git a/src/README.md b/src/README.md index 6922fbb..a5b412d 100644 --- a/src/README.md +++ b/src/README.md @@ -13,7 +13,7 @@ A Very Good Flutter Federated Plugin created by the [Very Good Ventures Team][ve Generated by the [Very Good CLI][very_good_cli_link] ๐Ÿค– -[coverage_badge]: app/coverage_badge.svg +[coverage_badge]: my_plugin/coverage_badge.svg [license_badge]: https://img.shields.io/badge/license-MIT-blue.svg [license_link]: https://opensource.org/licenses/MIT [logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only