diff --git a/doc/very_good_core.md b/doc/very_good_core.md index 5b9c18315..674c0f022 100644 --- a/doc/very_good_core.md +++ b/doc/very_good_core.md @@ -1,20 +1,47 @@ -# Very Good Core +# Very Good Core ๐Ÿฆ„ [![Very Good Ventures][logo]][very_good_ventures_link] Developed with ๐Ÿ’™ by [Very Good Ventures][very_good_ventures_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 Starter Project 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 Core you must have the [Flutter SDK][flutter_install_link] installed on your machine.** -## Getting Started ๐Ÿš€ +### Installation ๐Ÿ’ป + +For first time users, start by installing the [Very Good CLI from pub.dev][very_good_cli_link]. + +```sh +$ dart pub global activate very_good_cli +``` + +### Create a new Flutter Project ๐Ÿ†• + +Then, you can use the `very_good create` command just like you would `flutter create` + +![Very Good Create][very_good_create] + +**๐Ÿ’ก Upon first use, you will be prompted about anonymous usage statistics. You can adjust these settings at any time via the `--analytics` flag** + +```sh +# opt into anonymous usage statistics +very_good --analytics true + +# opt out of anonymous usage statistics +very_good --analytics false +``` + +### Running the Project โšก + +Once you have finished running `very_good create` with the project directory of your choice, you can change directories into the new project directory and install the dependencies + +```sh +$ cd my_app +$ flutter packages get +``` This project contains 3 flavors: @@ -37,9 +64,29 @@ $ flutter run --flavor production --target lib/main_production.dart _\*Very Good Core works on iOS, Android, and Web._ +Now your app is running ๐ŸŽ‰ + +--- + +## Why Very Good Core? ๐Ÿค” + +We liked the simplicity and developer experience of running `flutter create` when getting started on a new project. We wanted to provide a similar experience with `very_good create` which built on top of `flutter create` and includes the core standards and best practices we use at [Very Good Ventures][very_good_ventures_link]. + +We built the CLI to be extensible so it could potentially support multiple commands and templates in the future. + +## Project Structure and Architecture ๐Ÿ—๏ธ + +Although Very Good Core is fairly basic in terms of functionality, the architecture and project structure is intended to scale from a simple hobby project to a large production ready application. + +A folder-by-feature project structure is used to maintain a modular project structure which helps the project scale as the number of features and/or developers increase. In Very Good Core there is only a single feature (`counter`) to start but that will quickly change as you build out your project. Each feature usually consists of a `view` and a `cubit` (or `bloc`). The view is responsible for holding the UI (`Widgets`) which the user sees and interacts with and the `cubit`/`bloc` is responsible for containing the business logic needed to manage the state of the feature. For more details [read our best practices for building scalable apps][scalable_best_practices_blog_link]. + --- -## Running Tests ๐Ÿงช +## Testing ๐Ÿงช + +Very Good Core 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 ๐Ÿง‘โ€๐Ÿ”ฌ To run all unit and widget tests use the following command: @@ -158,13 +205,24 @@ Update the `CFBundleLocalizations` array in the `Info.plist` at `ios/Runner/Info } ``` -[coverage_badge]: ../coverage_badge.svg +--- + +## Continuous Integration ๐Ÿค– + +Very Good Core 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. 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]. + +[flutter_install_link]: https://flutter.dev/docs/get-started/install [flutter_localizations_link]: https://api.flutter.dev/flutter/flutter_localizations/flutter_localizations-library.html [internationalization_link]: https://flutter.dev/docs/development/accessibility-and-localization/internationalization -[license_badge]: https://img.shields.io/badge/license-MIT-blue.svg -[license_link]: https://opensource.org/licenses/MIT +[github_actions_link]: https://docs.github.com/en/actions/learn-github-actions [logo]: https://raw.githubusercontent.com/VeryGoodOpenSource/very_good_analysis/main/assets/vgv_logo.png -[very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg +[scalable_best_practices_blog_link]: https://verygood.ventures/blog/scalable-best-practices?utm_source=github&utm_medium=banner&utm_campaign=CLI [very_good_analysis_link]: https://pub.dev/packages/very_good_analysis -[very_good_cli_link]: https://github.com/VeryGoodOpenSource/very_good_cli +[very_good_core_link]: very_good_core.md +[very_good_coverage_link]: https://github.com/marketplace/actions/very-good-coverage +[very_good_cli_link]: https://pub.dev/packages/very_good_cli +[very_good_create]: https://raw.githubusercontent.com/VeryGoodOpenSource/very_good_cli/main/doc/assets/very_good_create.png +[very_good_testing_blog_link]: https://verygood.ventures/blog/guide-to-flutter-testing?utm_source=github&utm_medium=banner&utm_campaign=CLI [very_good_ventures_link]: https://verygood.ventures/?utm_source=github&utm_medium=banner&utm_campaign=core