chore: update docs (#27)

TBD54566975 · Dec 21, 2023 · 7a87e53 · 7a87e53
1 parent 875faf0
commit 7a87e53
Show file tree

Hide file tree

Showing 12 changed files with 84 additions and 257 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -1,24 +1 @@
-# This CODEOWNERS file denotes the project leads
-# and encodes their responsibilities for code review.
-
-# Instructions: At a minimum, replace the '@GITHUB_USER_NAME_GOES_HERE'
-# here with at least one project lead.
-
-# Lines starting with '#' are comments.
-# Each line is a file pattern followed by one or more owners.
-# The format is described: https://github.blog/2017-07-06-introducing-code-owners/
-
-# These owners will be the default owners for everything in the repo.
-*       @GITHUB_USER_NAME_GOES_HERE
-
-
-# -----------------------------------------------
-# BELOW THIS LINE ARE TEMPLATES, UNUSED
-# -----------------------------------------------
-# Order is important. The last matching pattern has the most precedence.
-# So if a pull request only touches javascript files, only these owners
-# will be requested to review.
-# *.js    @octocat @github/js
-
-# You can also use email addresses if you prefer.
-# docs/*  [email protected]
+*       @wesbillman
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ There are many ways to be an open source contributor, and we're here to help you
 
 * Propose ideas in our 
   [discord](https://discord.gg/tbd)
-* Raise an issue or feature request in our [issue tracker](LINK_HERE)  ___***FIX LINK AND REMOVE THIS NOTICE***___
+* Raise an issue or feature request in our [issue tracker](https://github.com/TBD54566975/flutter_starter/issues)
 * Help another contributor with one of their questions, or a code review
 * Suggest improvements to our Getting Started documentation by supplying a Pull Request
 * Evangelize our work together in conferences, podcasts, and social media spaces.
@@ -13,202 +13,31 @@ This guide is for you.
 
 ## Development Prerequisites
 
-___***UPDATE TABLE OF PROJECT DEPS AND INSTALLATION NOTES***___
+### Hermit
+The easiest way to get started with this project is to use [Hermit](https://cashapp.github.io/hermit/usage/get-started/). We recommend installing the [shell hooks](https://cashapp.github.io/hermit/usage/shell/) to automatically switch to the correct version of Flutter and other dependencies for this project.
 
-| Requirement | Tested Version | Installation Instructions                            |
-|-------------|----------------|------------------------------------------------------|
-| Go          | 1.17.6         |[go.dev](https://go.dev/doc/tutorial/compile-install) |
-| Mage        | 1.12.1         |[magefile.org](https://magefile.org/)                 |
-| Java        | 17.0.2         | Below, recommended via [SDKMan](https://sdkman.io)   |
-
-### Go
-
-This project is written in Go, a modern, open source programming language. 
-
-You may verify your `go` installation via the terminal:
-
-```
-$> go version
-go version go1.17.6 darwin/amd64
-```
-
-If you do not have go, we recommend installing it by:
-
-#### MacOS
-
-##### Homebrew
-```
-$> brew install go
-```
-
-#### Linux
-
-See the [Go Installation Documentation](https://go.dev/doc/install).
-
-### Mage
-
-The build is run by Mage.
-
-You may verify your `mage` installation via the terminal:
-
-```
-$> mage --version
-Mage Build Tool 1.12.1
-Build Date: 2021-12-15T21:00:02Z
-Commit: 2f1ec40
-built with: go1.17.6
-```
-
-#### MacOS
-
-##### Homebrew
-
-```
-$> brew install mage
-```
-
-#### Linux
-
-Installation instructions are on the [Magefile home page](https://magefile.org/).
-
-### Java
-
-This project is written in Java, a typesafe, compiled programming language. 
-
-You may verify your `java` installation via the terminal by running `java -version`.
-
-If you do not have Java, we recommend installing it 
-via [SDKMan](https://sdkman.io/install). This is a project which will allow you 
-to easily install the Java Development Kit (JDK), runtime (JRE), and related frameworks, 
-build tools, and runtimes.
-
-After you've installed SDKMan, you may install Java:
-
-#### SDKMan (cross-platform instructions)
-
-```shell
-$> sdk install java 
- ...
-Do you want java 17.0.2-open to be set as default? (Y/n): Y
-Setting java 17.0.2-open as default.
-```
-
-You may test your installation:
+<details>
+  <summary>Installing dependecies without hermit (the hard way)</summary>
 
-```shell
-$> java -version
-openjdk version "17.0.2" 2022-01-18
-OpenJDK Runtime Environment (build 17.0.2+8-86)
-OpenJDK 64-Bit Server VM (build 17.0.2+8-86, mixed mode, sharing)
-```
-
----
-**NOTE**
-
-You may additionally look for other Java versions to install by running `sdk list java`:
-
-...or other installation candidates like Apache Ant, Apache Maven, etc, by running `sdk list`.
-
-Consult the SDKMan documentation for more info.
-
----
-
-## Build (Mage)
-
-```
-$> mage build
-```
-
-## Build (Java / Gradle)
-
-### macOS / Linux
-```shell
-$> ./gradlew build
-```
-
-### Windows
-```shell
-$> gradlew.bat build
-```
-
-## Test (Mage)
-
-```
-$> mage test
-```
+  | Requirement | Tested Version | Installation Instructions                            |
+|-------------|----------------|------------------------------------------------------|
+| Flutter     | 3.16.5         |[flutter.dev](https://docs.flutter.dev/get-started/install) |
+| Just        | 1.16.0         |[https://github.com/casey/just](https://github.com/casey/just)                 |
 
-## Test (Java / Gradle)
+</details>
 
-### macOS / Linux
-```shell
-$> ./gradlew test
-```
-
-### Windows
-```shell
-$> gradlew.bat test
-```
+### Development
 
----
-**NOTE**
+It's recommended to use VSCode for Flutter development. This will allow you to run, debug, test, etc. from within the IDE. You can also use Android Studio if you prefer.
 
-You may also combine Gradle build targets in one call, like:
+### Just tasks
 
-```shell
-$> ./gradlew clean build test
+This project uses [Just](https://github.com/casey/just) as a command runner. You can see all available tasks by running `just --list`. The most common tasks are:
+```bash
+run           # Run the Flutter app
+test          # Run tests
+generate      # Generate code (localization, etc.)
+get           # Get Flutter and Dart packages
 ```
 
----
-
-## Communications
-
-### Issues
-
-Anyone from the community is welcome (and encouraged!) to raise issues via 
-[GitHub Issues](LINK_HERE)  ___***FIX LINK AND REMOVE THIS NOTICE***___.
-
-### Discussions
-
-Design discussions and proposals take place in our [discord](https://discord.gg/tbd).
-
-We advocate an asynchronous, written debate model - so write up your thoughts and invite the community to join in!
-
-### Continuous Integration
-
-Build and Test cycles are run on every commit to every branch on [CircleCI](LINK_HERE).
-
- ___***FIX LINK ABOVE AND REMOVE THIS NOTICE***___
-
-## Contribution
-
-We review contributions to the codebase via GitHub's Pull Request mechanism. We have 
-the following guidelines to ease your experience and help our leads respond quickly 
-to your valuable work:
-
-* Start by proposing a change either in Issues (most appropriate for small 
-  change requests or bug fixes) or in Discussions (most appropriate for design 
-  and architecture considerations, proposing a new feature, or where you'd 
-  like insight and feedback)
-* Cultivate consensus around your ideas; the project leads will help you 
-  pre-flight how beneficial the proposal might be to the project. Developing early 
-  buy-in will help others understand what you're looking to do, and give you a 
-  greater chance of your contributions making it into the codebase! No one wants to 
-  see work done in an area that's unlikely to be incorporated into the codebase.
-* Fork the repo into your own namespace/remote
-* Work in a dedicated feature branch. Atlassian wrote a great 
-  [description of this workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow)
-* When you're ready to offer your work to the project, first:
-* Squash your commits into a single one (or an appropriate small number of commits), and 
-  rebase atop the upstream `main` branch. This will limit the potential for merge 
-  conflicts during review, and helps keep the audit trail clean. A good writeup for 
-  how this is done is 
-  [here](https://medium.com/@slamflipstrom/a-beginners-guide-to-squashing-commits-with-git-rebase-8185cf6e62ec), and if you're 
-  having trouble - feel free to ask a member or the community for help or leave the commits as-is, and flag that you'd like 
-  rebasing assistance in your PR! We're here to support you.
-* Open a PR in the project to bring in the code from your feature branch.
-* The maintainers noted in the `CODEOWNERS` file will review your PR and optionally 
-  open a discussion about its contents before moving forward.
-* Remain responsive to follow-up questions, be open to making requested changes, and...
-  You're a contributor!
-* And remember to respect everyone in our global development community. Guidelines 
-  are established in our `CODE_OF_CONDUCT.md`.
+These can be run with `just <task>`. For example, to run the app, you can run `just run`.
diff --git a/Justfile b/Justfile
@@ -2,7 +2,7 @@
 run:
   flutter run
 
-# Get packages
+# Get Flutter and Dart packages
 get:
   #!/bin/bash
   echo "Getting dependencies for main project"
@@ -50,7 +50,7 @@ analyze:
     fi \
   done  
 
-# Generate code
+# Generate code (localization, etc.)
 generate:
   flutter gen-l10n
 

diff --git a/README.md b/README.md
@@ -1,33 +1,53 @@
-# $PROJECT_NAME README
+# Flutter Starter
 
-Congrats, project leads! You got a new project to grow!
+![Build Status](https://github.com/TBD54566975/flutter_starter/actions/workflows/ci.yml/badge.svg)
 
-This stub is meant to help you form a strong community around your work. It's yours to adapt, and may 
-diverge from this initial structure. Just keep the files seeded in this repo, and the rest is yours to evolve! 
+A starter project for Flutter apps. This start setups up best practices for Flutter apps, including:
+* Localization
+* Theming
+* CI/CD
+* Testing
+* Code generation
+* Dependency injection and state management (via [Riverpod](https://riverpod.dev/))
+* Linting and formatting
+* Separate application layers implemented via sub-packages (e.g. `services`)
 
-## Introduction
+## Quick start
 
-Orient users to the project here. This is a good place to start with an assumption
-that the user knows very little - so start with the Big Picture and show how this
-project fits into it. It may be good to reference/link the broader architecture in the
-`collaboration` repo or the developer site here.
+1. Clone this repo
+2. Use [Hermit](https://cashapp.github.io/hermit/usage/get-started/) to install required dependencies (or manually install and setup [Flutter](https://docs.flutter.dev/get-started/install) and [Just](https://github.com/casey/just))
+3. Run `just get` to install dependencies
+4. Run `just run` to run the app
 
-Then maybe a dive into what this project does.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for more details.
 
-Diagrams and other visuals are helpful here. Perhaps code snippets showing usage.
 
-Project leads should complete, alongside this `README`:
-* [CODEOWNERS](./CODEOWNERS) - set project lead(s)
-* [CONTRIBUTING.md](./CONTRIBUTING.md) - Fill out how to: install prereqs, build, test, run, access CI, chat, discuss, file issues
-* [Bug-report.md](.github/ISSUE_TEMPLATE/bug-report.md) - Fill out `Assignees` add codeowners @names
-* [config.yml](.github/ISSUE_TEMPLATE/config.yml) - remove "(/add your discord channel..)" and replace the url with your Discord channel if applicable
+## TBD theme
 
-The other files in this template repo may be used as-is:
-* [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
-* [GOVERNANCE.md](./GOVERNANCE.md)
-* [LICENSE](./LICENSE)
+The theme is defined in `lib/shared/theme.dart`. It is a `ThemeData` object that is used by the `MaterialApp` and setup during app initialization in  `lib/features/app/app.dart`.
 
-## Project Resources
+> Note: The theme is currently a work in progress. In the future, we might move the theme out to a dedicated TBD Design System package.
+
+### Example screens
+
+#### Counter
+<p align="center">
+  <img src="docs/counter-light.png" alt="First Image" width="400" />
+  <img src="docs/counter-dark.png" alt="Second Image" width="400" />
+</p>
+
+#### Todos
+<p align="center">
+  <img src="docs/todos-light.png" alt="First Image" width="400" />
+  <img src="docs/todos-dark.png" alt="Second Image" width="400" />
+</p>
+
+<p align="center">
+  <img src="docs/todo-light.png" alt="First Image" width="400" />
+  <img src="docs/todo-dark.png" alt="Second Image" width="400" />
+</p>
+
+## Project resources
 
 | Resource                                   | Description                                                                    |
 | ------------------------------------------ | ------------------------------------------------------------------------------ |

diff --git a/docs/counter-dark.png b/docs/counter-dark.png
diff --git a/docs/counter-light.png b/docs/counter-light.png
diff --git a/docs/todo-dark.png b/docs/todo-dark.png
diff --git a/docs/todo-light.png b/docs/todo-light.png
diff --git a/docs/todos-dark.png b/docs/todos-dark.png
diff --git a/docs/todos-light.png b/docs/todos-light.png
diff --git a/lib/features/counter/counter_page.dart b/lib/features/counter/counter_page.dart
@@ -12,18 +12,21 @@ class CounterPage extends HookWidget {
     return Scaffold(
       appBar: AppBar(title: Text(Loc.of(context).appName)),
       body: Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: <Widget>[
-            Text(
-              Loc.of(context).youHavePushedTheButton,
-              textAlign: TextAlign.center,
-            ),
-            Text(
-              '${counter.value}',
-              style: Theme.of(context).textTheme.headlineMedium,
-            ),
-          ],
+        child: Padding(
+          padding: const EdgeInsets.all(16),
+          child: Column(
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: <Widget>[
+              Text(
+                Loc.of(context).youHavePushedTheButton,
+                textAlign: TextAlign.center,
+              ),
+              Text(
+                '${counter.value}',
+                style: Theme.of(context).textTheme.headlineMedium,
+              ),
+            ],
+          ),
         ),
       ),
       floatingActionButton: FloatingActionButton(