diff --git a/.gitignore b/.gitignore index 49ba9656..e80c164b 100644 --- a/.gitignore +++ b/.gitignore @@ -13,4 +13,5 @@ build/ # Files and directories created by mason .mason/ -mason-lock.json \ No newline at end of file +mason-lock.json +output/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..cefc3491 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,123 @@ +# πŸ¦„ Contributing to Very Good Core + +This CONTRIBUTING file is for a developer that wants to modify or contribute to the package:project_uploader. If you are interested in solely generating a project using Very Good Core, please refer to the [README](README.md) file. + +## Opening an issue + +We highly recommend [creating an issue][bug_report_link] if you have found a bug, want to suggest a feature, or recommend a change. Please do not immediately open a pull request. Opening an issue first allows us to reach an agreement on a fix before you put significant effort into a pull request. + +When reporting a bug, please use the built-in [Bug Report][bug_report_link] template and provide as much information as possible including detailed reproduction steps. Once one of the package maintainers has reviewed the issue and we reach an agreement on the fix, open a pull request. + +[bug_report_link]: https://github.com/VeryGoodOpenSource/very_good_core/issues + +## Developing for Very Good Core + +To develop for Very Good Core you will need to become familiar with Very Good Ventures processes and conventions: + +### Setting up your local development environment + +1. Install a valid [Flutter SDK](https://docs.flutter.dev/get-started/install) in your local environment. Compatible Flutter SDK versions with Very Good Core can be found within the [Flutter release archive](https://docs.flutter.dev/release/archive), ensure it has a Dart version compatible with [Very Good Core's Dart version constraint](). + +2. Install [Very Good CLI](https://cli.vgv.dev/docs/overview#installing) in your local environment: + +```sh +# 🎯 Activate Very Good CLI from https://pub.dev +dart pub global activate very_good_cli +``` + +3. Install [Mason](https://github.com/felangel/mason/tree/master/packages/mason_cli#installation) in your local environment: + +```sh +# 🎯 Activate Mason from https://pub.dev +dart pub global activate mason_cli +``` + +πŸ’‘ **Note**: If you're not familiar with Mason, read its [documentation](https://docs.brickhub.dev/) or watch our [Mason Demonstration](https://www.youtube.com/watch?v=G4PTjA6tpTU). + +3. Get all bricks in Very Good Core's `mason.yaml`: + +```sh +# πŸ“‚ Get all bricks in Very Good Core (from project root): +mason get +``` + +4. Generate the template locally: + +```sh +# 🧱 Generate a project using the local Very Good Core version +mason make very_good_core --config-path brick/config.json --output-dir output --watch +``` + +This will generate a project using Very Good Core under [`output`](output) with the variables specified by the [configuration](brick/config.json) file. When any file under [`__brick__`](brick/__brick__/) is changed. + +### Creating a Pull Request + +Before creating a Pull Request please: + +1. [Fork](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) the [GitHub repository](https://github.com/VeryGoodOpenSource/very_good_core) and create your branch from `main`: + +```sh +# πŸͺ΅ Branch from `main` +git branch +git checkout +``` + +Where `` is an appropriate name describing your change. + +2. Get all bricks in Very Good Core's `mason.yaml`: + +```sh +# πŸ“‚ Get all bricks in Very Good Core (from project root): +mason get +``` + +3. Generate the template locally: + +```sh +# 🧱 Generate a project using the local Very Good Core brick (from project root) +mason make very_good_core --config-path brick/config.json --output-dir output +``` + +4. Add tests! Pull Requests without 100% test coverage will **not** be merged. If you're unsure on how to do so watch our [Testing Fundamentals Course](https://www.youtube.com/watch?v=M_eZg-X789w&list=PLprI2satkVdFwpxo_bjFkCxXz5RluG8FY). + +```sh +# πŸ“Š Check code coverage (from output/test_app) +very_good test -x pull-request-only --min-coverage 100 +``` + +Optionally, you can generate a detailed coverage report: + +```sh +# πŸ“Š Generate coverage report (from output/test_app) +very_good test -x pull-request-only --coverage + +# πŸ•ΈοΈ Generate a readable HTML website (from output/test_app) +genhtml -o coverage/html coverage/lcov.info + +# πŸ‘€ Open the coverage report HTML website (from output/test_app) +open coverage/html/index.html +``` + +5. Ensure the generated project is well formatted: + +```sh +# 🧼 Run Dart's formatter (from output/test_app) +dart format lib test --set-exit-if-changed +``` + +6. Analyze the generated project: + +```sh +# πŸ” Run Dart's analyzer (from output/test_app) +dart analyze --fatal-infos --fatal-warnings . +``` + +πŸ’‘ **Note**: Our repositories use [Very Good Analysis](https://github.com/VeryGoodOpenSource/very_good_analysis). + +7. Ensure you have a meaningful [semantic][conventional_commits_link] commit message. + +8. Create the Pull Request with a meaningful description, linking to the original issue where possible. + +9. Verify that all [status checks](https://github.com/VeryGoodOpenSource/very_good_core/actions/) are passing for your Pull Request once they have been approved to run by a maintainer. + +πŸ’‘ **Note**: While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional work, tests, or other changes before your pull request can be accepted. diff --git a/README.md b/README.md index cff75be3..567c3f4b 100644 --- a/README.md +++ b/README.md @@ -5,181 +5,57 @@ 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]. +A Very Good Flutter Starter Project created by the Very Good Ventures Team πŸ¦„ -Generated by the [Very Good CLI][very_good_cli_link] πŸ€– +πŸ’‘ **Note**: This README file is for a developer that wants to use Very Good Core. For contributing information please refer to the [CONTRIBUTING file](./CONTRIBUTING.md). --- -## Getting Started πŸš€ +## What's Included ✨ -This project contains 3 flavors: +Out of the box, Very Good Core includes: -- development -- staging -- production +- βœ… [Cross Platform Support][flutter_cross_platform_link] - Built-in support for iOS, Android, Web, and Windows (MacOS/Linux coming soon!) +- βœ… [Build Flavors][flutter_flavors_link] - Multiple flavor support for development, staging, and production +- βœ… [Internationalization Support][internationalization_link] - Internationalization support using synthetic code generation to streamline the development process +- βœ… [Sound Null-Safety][null_safety_link] - No more null-dereference exceptions at runtime. Develop with a sound, static type system. +- βœ… [Bloc][bloc_link] - Integrated bloc architecture for scalable, testable code which offers a clear separation between business logic and presentation +- βœ… [Testing][testing_link] - Unit and Widget Tests with 100% line coverage (Integration Tests coming soon!) +- βœ… [Logging][logging_link] - Built-in, extensible logging to capture uncaught Flutter and Dart Exceptions +- βœ… [Very Good Analysis][very_good_analysis_link] - Strict Lint Rules which are used at [Very Good Ventures][very_good_ventures_link] +- βœ… [Continuous Integration][github_actions_link] - Lint, format, test, and enforce code coverage using [GitHub Actions][github_actions_link] +- βœ… Dependabot Integration -To run the desired flavor either use the launch configuration in VSCode/Android Studio or use the following commands: +_\* Learn more at [Flutter Starter App: Very Good Core & CLI][very_good_cli_blog_link]_ -```sh -# Development -$ flutter run --flavor development --target lib/main_development.dart - -# Staging -$ flutter run --flavor staging --target lib/main_staging.dart - -# Production -$ flutter run --flavor production --target lib/main_production.dart -``` - -_\*Very Good Core works on iOS, Android, Web, and Windows._ - ---- +## Quick Start πŸš€ -## Running Tests πŸ§ͺ +1. Install a valid [Flutter SDK](https://docs.flutter.dev/get-started/install) in your local environment. Compatible Flutter SDK versions with [Very Good CLI][very_good_cli_link] can be found within the [Flutter release archive](https://docs.flutter.dev/release/archive), ensure it has a Dart version compatible with [Very Good CLI's Dart version constraint](https://github.com/VeryGoodOpenSource/very_good_cli/blob/main/pubspec.yaml). -To run all unit and widget tests use the following command: +2. [Install Very Good CLI](https://cli.vgv.dev/docs/overview#installing): ```sh -$ flutter test --coverage --test-randomize-ordering-seed random +# πŸ’» Install Very Good CLI from pub.dev +dart pub global activate very_good_cli ``` -To view the generated coverage report you can use [lcov](https://github.com/linux-test-project/lcov). +3. Generate a project using Very Good Core: ```sh -# Generate Coverage Report -$ genhtml coverage/lcov.info -o coverage/ - -# Open Coverage Report -$ open coverage/index.html +# πŸš€ Create a new project using Very Good Core +very_good create flutter_app ``` ---- - -## Working with Translations 🌐 - -This project relies on [flutter_localizations][flutter_localizations_link] and follows the [official internationalization guide for Flutter][internationalization_link]. - -### Adding Strings - -1. To add a new localizable string, open the `app_en.arb` file at `lib/l10n/arb/app_en.arb`. - -```arb -{ - "@@locale": "en", - "counterAppBarTitle": "Counter", - "@counterAppBarTitle": { - "description": "Text shown in the AppBar of the Counter Page" - } -} -``` - -2. Then add a new key/value and description - -```arb -{ - "@@locale": "en", - "counterAppBarTitle": "Counter", - "@counterAppBarTitle": { - "description": "Text shown in the AppBar of the Counter Page" - }, - "helloWorld": "Hello World", - "@helloWorld": { - "description": "Hello World Text" - } -} -``` - -3. Use the new string - -```dart -import 'package:very_good_core/l10n/l10n.dart'; - -@override -Widget build(BuildContext context) { - final l10n = context.l10n; - return Text(l10n.helloWorld); -} -``` - -### Adding Supported Locales - -Update the `CFBundleLocalizations` array in the `Info.plist` at `ios/Runner/Info.plist` to include the new locale. - -```xml - ... - - CFBundleLocalizations - - en - es - - - ... -``` - -### Adding Translations - -1. For each supported locale, add a new ARB file in `lib/l10n/arb`. - -``` -β”œβ”€β”€ l10n -β”‚ β”œβ”€β”€ arb -β”‚ β”‚ β”œβ”€β”€ app_en.arb -β”‚ β”‚ └── app_es.arb -``` - -2. Add the translated strings to each `.arb` file: - -`app_en.arb` - -```arb -{ - "@@locale": "en", - "counterAppBarTitle": "Counter", - "@counterAppBarTitle": { - "description": "Text shown in the AppBar of the Counter Page" - } -} -``` - -`app_es.arb` - -```arb -{ - "@@locale": "es", - "counterAppBarTitle": "Contador", - "@counterAppBarTitle": { - "description": "Texto mostrado en la AppBar de la pΓ‘gina del contador" - } -} -``` - -### Generating Translations - -To use the latest translations changes, you will need to generate them: - -1. Generate localizations for the current project: - -```sh -flutter gen-l10n --arb-dir="lib/l10n/arb" -``` +Where `` is the name of your project. -Alternatively, run `flutter run` and code generation will take place automatically. +πŸ’‘ **Note**: Optionally, you can [generate a project using Very Good Core with mason](https://brickhub.dev/bricks/very_good_core/0.4.0#usage). -[coverage_badge]: src/my_app/coverage_badge.svg -[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 [logo_black]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_black.png#gh-light-mode-only [logo_white]: https://raw.githubusercontent.com/VGVentures/very_good_brand/main/styles/README/vgv_logo_white.png#gh-dark-mode-only -[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