docs: update readme, etc

.github/pull_request_template.md

@@ -1,42 +1,41 @@
-<!--
-  Thanks for contributing!
-
-  Provide a description of your changes below and a general summary in the title.
-
-  Please look at the following checklist to ensure that your PR can be accepted quickly:
--->
+> Thanks for contributing!
+> Provide a description of your changes below and a general summary in the title.
+> Please look at the following checklist to ensure that your PR can be accepted quickly:
+>
+> Once you've read over these comments, you should delete them.
 
 ## Description
 
-<!-- Describe your changes. -->
+> Describe your changes in a sentence or two.
 
 This PR...
 
-_Closes: #issue_
+> Which issue does this close?
+> If none, write up a more detailed issue real quick so any non-development-related discussion can go there.
+
+_**Closes:** #issue_
 
 ## Type of Change
 
-<!-- Delete all non-applicable categories. -->
+> Delete all non-applicable categories.
 
-- ✨ New feature (non-breaking change which adds functionality)
-- 🛠️ Bug fix (non-breaking change which fixes an issue)
-- ❌ Breaking change (fix or feature that would cause existing functionality to change)
+- ✨ New feature
+- 🐛 Bug fix
+- 💥 Breaking change
 - 📝 Documentation
-- 🧹 Code refactor
+- ♻️ Code refactor
 - 🎨 Style
-- 🔥 Performance Improvements
+- ⚡️ Performance improvements
+- 🧹 Reduce tech debt
+- 🔥 Remove obsolete, unused things
 - 🧪 Test
-- 🔁 CI
-- 🤖 Build configuration change
-- ⏪ Revert
+- 💚 CI
+- 🛠️ Build configuration change
+- ⏪️ Revert
 - 🗑️ Chore
 
-<!--
-
-## Poem
-
-<!- Because, well, why not? ->
+<!-- ## Poem
 
-copilot:poem
+> Because, well, why not?
 
--->
+copilot:poem -->

.markdownlint-cli2.jsonc

@@ -3,8 +3,5 @@
     "line-length": false, // no one cares
     "no-emphasis-as-heading": false, // to many false positives
     "first-line-heading": false // github templates needed an ignore
-  },
-
-  // Disable inline config comments
-  "noInlineConfig": true
+  }
 }

.vscode/extensions.json

@@ -9,15 +9,15 @@
     "google.arb-editor",
     "tamasfe.even-better-toml",
     "redhat.vscode-yaml",
-    "simonsiefke.svg-preview",
+    "sndst00m.vscode-native-svg-preview",
     "ms-vsliveshare.vsliveshare",
     "eamodio.gitlens",
     "bbenoist.nix",
     "streetsidesoftware.code-spell-checker",
     "esbenp.prettier-vscode",
     "foam.foam-vscode",
     "tyriar.luna-paint",
-    "pkief.material-icon-theme",
-    "alefragnani.project-manager"
+    "pflannery.vscode-versionlens",
+    "streetsidesoftware.code-spell-checker-spanish"
   ]
 }

.vscode/tasks.json

@@ -182,7 +182,7 @@
       "options": [
         { "label": "run a build", "value": "build" },
         { "label": "watch the filesystem, run many builds", "value": "watch" },
-        { "label": "make a server", "value": "serve" },
+        { "label": "run a server to debug perf with", "value": "serve" },
         { "label": "run our tests", "value": "test" },
         { "label": "run just one build, not all of them", "value": "run" },
         { "label": "clean up from old builds", "value": "clean" }

README.md

@@ -1,4 +1,23 @@
-# Pirate Code 3.0
+<!-- markdownlint-disable -->
+<h1 align="center">
+  <a target="_self" href="https://github.com/PSDTools/app">
+    <img style="width: 60px" src="https://psdr3.org/images/logos/psdr3-450.png" />
+  </a>
+</h1>
+<div align="center">
+  <h2 align="center">
+  Pirate Code 3.0 - An App for the <a href="https://psdr3.org/"><strong>Pattonville School District</strong></a>
+  </h2>
+  <div align="center">
+    <a target="_self" href="https://github.com/PSDTools/app">
+      <img align="center" style="width: 80%; height: auto" src="https://raw.githubusercontent.com/PSDTools/.github/main/metrics/followup/app_followup.svg" />
+    </a>
+    <a target="_self" href="https://github.com/PSDTools">
+      <img align="center" style="width: 80%; height: auto" src="https://raw.githubusercontent.com/PSDTools/.github/main/metrics/metrics.svg" />
+    </a>
+  </div>
+</div>
+<!-- markdownlint-restore -->
 
 [![Netlify Status][deploys_badge]][deploys_link]
 [![Dart][ci_dart_badge]][ci_dart_link]
@@ -22,7 +41,7 @@ We don't believe that READMEs should be a 15 Terabyte[^1] file, so we broke it u
 [ci_dart_link]: https://github.com/PSDTools/app/actions/workflows/dart.yaml
 [ci_spell_badge]: https://github.com/PSDTools/app/actions/workflows/markdown.yaml/badge.svg?branch=main
 [ci_spell_link]: https://github.com/PSDTools/app/actions/workflows/markdown.yaml
-[coverage_badge]: https://img.shields.io/badge/coverage-30%25-CB2431.svg
+[coverage_badge]: https://img.shields.io/badge/coverage-13%25-CB2431.svg
 [deploys_badge]: https://api.netlify.com/api/v1/badges/25b0c44e-21b7-423c-a914-32aa4b23b708/deploy-status
 [deploys_link]: https://app.netlify.com/sites/pattonville-wallet/deploys
 [very_good_analysis_badge]: https://img.shields.io/badge/style-very_good_analysis-B22C89.svg

cspell.json

@@ -2,10 +2,18 @@
   "version": "0.2",
   "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
   "dictionaries": [
+    "project",
     "vgv_allowed",
     "vgv_forbidden"
   ],
   "dictionaryDefinitions": [
+    {
+      "name": "project",
+      "path": "./project_words.txt",
+      "description": "Words used in this project.",
+      "addWords": true
+
+    },
     {
       "name": "vgv_allowed",
       "path": "https://raw.githubusercontent.com/verygoodopensource/very_good_dictionaries/main/allowed.txt",
@@ -18,33 +26,21 @@
     }
   ],
   "useGitignore": true,
-  "words": [
-    "!AppWrite",
-    "Appwrite",
-    "ARGB",
-    "contador",
-    "Contador",
-    "Cupertino",
-    "Dafoe",
-    "dartdoc",
-    "Decap",
-    "dhttpd",
-    "fullscreen",
-    "Instructure",
-    "localizable",
-    "mostrado",
-    "nodoc",
-    "página",
-    "Pattonville",
-    "psdr3",
-    "riverpod",
-    "Texto",
-    "WCAG",
-    "Widgetbook"
-  ],
   "globRoot": ".",
   "ignorePaths": [
-    "lib/l10n/arb/*.arb",
-    "cspell.json",
+    "project_words.txt"
   ],
+  "features": {
+    "weighted-suggestions": true
+  },
+  "allowCompoundWords": true,
+  "caseSensitive": true,
+  "language": "en-US",
+  "validateDirectives": true,
+  "overrides": [
+    {
+      "language": "es,en-US",
+      "filename": "lib/l10n/arb/app_es.arb"
+    }
+  ]
 }

dartdoc_options.yaml

@@ -12,7 +12,15 @@ dartdoc:
     Translations:
       markdown: doc/translations.md
       name: Translations
-  categoryOrder: ["Getting Started", "Testing", "Translations", "C4Diagram"]
+    Server:
+      markdown: doc/docker.md
+      name: Appwrite
+  categoryOrder:
+    - "Getting Started"
+    - "Testing"
+    - "Translations"
+    - "C4Diagram"
+    - "Server"
   showUndocumentedCategories: true
   includeExternal: ["test/helpers/helpers.dart"]
   linkToSource:

doc/c4-diagram.md

@@ -6,7 +6,7 @@ A diagram of our systems, using [Mermaid.js][mermaid]/[PlantUML][plantuml].
 C4Context
   title Pirate Context Diagram
 
-  Enterprise_Boundary(pattonville, "Pattonville") {
+  Enterprise_Boundary(district, "Pattonville") {
     Person(admin, "Admin", "A school/district admin, one who can can see trends as well as give tokens.")
     Person(teachers, "Teachers", "A teacher, the one giving tokens.")
     Person_Ext(council, "Student Council", "The ones removing tokens.")

doc/docker.md

@@ -0,0 +1,46 @@
+# Using Docker 🐳
+
+To locally run the server, you'll need to use the [Docker](https://www.docker.com/) virtualization software.
+
+## Install Docker
+
+To install Docker, follow the instructions on the "[Install Docker Desktop on Mac](https://docs.docker.com/desktop/install/mac-install/)" docs page.
+You **must** use the default settings in order to allow binding to `localhost:80`, etc.
+
+## Install Appwrite Server
+
+To install Appwrite using Docker, run the following command,
+substituting `1.4.1` with the newest Appwrite Server version supported by the Appwrite SDK currently in use:
+
+```sh
+docker run -it --rm --volume /var/run/docker.sock:/var/run/docker.sock --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw --entrypoint="install" appwrite/appwrite:1.4.1
+```
+
+## Create a new Appwrite Project
+
+> **Note:**
+> Eventually, we'll need to write a script to automate this.
+
+1. Navigate to [`localhost:80/login`](http://localhost/login)
+1. Click the sign up button.
+   1. You'll want to remember your password somewhere.
+1. Create a new project
+   1. Set the id to `pirate-code`.
+1. Create a new database.
+   1. It should be in the `pirate-code` project.
+   1. Set the id to `pirate-coins`.
+1. Create a new collection.
+
+   1. It should be in the `pirate-coins` database.
+   1. Set the id to `coins`.
+   1. Set the permissions to the `coins` collection to the following:
+
+      | Type | Create | Read | Write | Delete |
+      | ---- | ------ | ---- | ----- | ------ |
+      | All  | ✅     | ✅   | ✅    | ❌     |
+
+1. Verify that `.env.example` was renamed to `.env`, and that `direnv` works.
+1. Run the "Dart: run build_runner" VS Code task.
+1. Launch the app using the VS Code Run and Debug launcher.
+   1. See if the app works.
+   1. If not, file an issue with the documentation label.

doc/translations.md

@@ -44,5 +44,17 @@ This project relies on [flutter_localizations][flutter_localizations_link] and f
    }
    ```
 
+## Generating Translations
+
+To use the latest translations changes, you will need to generate them my using the Flutter CLI to generate the updated localizations:
+
+```sh
+flutter gen-l10n
+```
+
+## L10nization
+
+Alternatively, you can use the [L10nization](https://marketplace.visualstudio.com/items?itemName=lsaudon.l10nization) VS Code extension, which offers quick fixes for non-localized text. To use it, highlight the text from quote-to-shining-quote, and follow the prompts.
+
 [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

lib/l10n/arb/app_en.arb

@@ -30,7 +30,7 @@
       }
     }
   },
-  "howManyCoins": "You currently have {coins} coins.",
+  "howManyCoins": "{coins, plural, other{You have {coins} coins.} zero{You have no coins.} one{You have one coin.} two{You have two coins.}}",
   "@howManyCoins": {
     "type": "text",
     "description": "The text which is displayed to show the number of coins on the stats page.",

lib/l10n/arb/app_es.arb

@@ -30,12 +30,23 @@
       }
     }
   },
-  "howManyCoins": "You have {coins} coins.",
+  "howManyCoins": "{coins, plural, other{Actualmente tienes {coins} monedas.} zero{Actualmente no tienes monedas.} one{Actualmente tienes una moneda.} two{Actualmente tienes dos monedas.}}",
   "@howManyCoins": {
     "type": "text",
     "description": "El texto que se muestra para mostrar el número de monedas en la página de estadísticas.",
     "placeholders": {
       "coins": {
+        "type": "int",
+        "example": "1"
+      }
+    }
+  },
+  "newMessages": "test {newMessages, plural, =0{No new messages} =1 {One new message} two{Two new Messages} other {test {newMessages} new messages}}",
+  "@newMessages": {
+    "type": "text",
+    "description": "Number of new messages in inbox.",
+    "placeholders": {
+      "newMessages": {
         "type": "int"
       }
     }

lib/utils/api.dart

@@ -1,4 +1,6 @@
 /// The api utilities.
+///
+/// {@Category Server}
 library;
 
 import "package:appwrite/appwrite.dart";

project_words.txt

@@ -0,0 +1,21 @@
+!AppWrite
+Appwrite
+ARGB
+Autentícate
+cupertino
+Dafoe
+dartdoc
+Decap
+dhttpd
+direnv
+fullscreen
+Instructure
+localizable
+Pattonville
+!pattonville
+psdr3
+riverpod
+Texto
+WCAG
+Widgetbook
+l10nization