Make a bunch of adds/edits to ARCH/CONTRIB/README

So, means we're working on #54 as well as #48 at the same time, now.

ARCHITECTURE.md

@@ -0,0 +1,33 @@
+# Architecture
+
+This document describes the high-level architecture of this TypeScript-based
+Firefox extension project. If you're trying to familiarize yourself with the
+codebase, this is the place to start!
+
+<!-- toc -->
+
+- [High-Level Description](#high-level-description)
+- [Tooling](#tooling)
+- [Code Map](#code-map)
+  * [Directory Structure](#directory-structure)
+  * [Code Semantics](#code-semantics)
+
+<!-- tocstop -->
+
+## High-Level Description
+
+...
+
+## Tooling
+
+- TypeScript
+- Webpack
+- Prettier
+
+## Code Map
+
+### Directory Structure
+
+`mermaid diagram`
+
+### Code Semantics

CONTRIBUTING.md

@@ -4,30 +4,134 @@ Thanks for your interest in contributing to the BGA Wingspan Scraper Firefox
 extension! The aim of this document is to provide the information you need to
 get started smoothly on a contribution.
 
-If you have any questions, please drop me a line on Twitter/X ([@btskinn]) or Fosstodon ([@btskinn@fosstodon.org]) or open an [issue].
+If you have any questions, please drop me a line on Twitter/X ([@btskinn]) or
+Fosstodon ([@btskinn@fosstodon.org]) or open an [issue].
 
 <!-- toc -->
 
+- [Project Stack](#project-stack)
 - [Project Setup](#project-setup)
-- [Test Heading 2](#test-heading-2)
+- [Working with git](#working-with-git)
+- [Building](#building)
+  * [Dev Builds](#dev-builds)
+  * [Production Builds](#production-builds)
+- [Testing](#testing)
+- [CHANGELOG](#changelog)
+- [License](#license)
 
 <!-- tocstop -->
 
+## Project Stack
+
+This is a TypeScript codebase set up with Prettier auto-formatting, which builds
+to a single-file `.js` module via Webpack. For more detailed information on the
+project architecture, see [`ARCHITECTURE.md`][arch].
+
 ## Project Setup
 
-Before starting work on this project, you'll need to install a current version of Node.js, either using a system package manager or by [downloading an installer].
+Before starting work on this project, you'll need to install a current version
+of Node.js, either using a system package manager or by
+[downloading an installer].
 
 Start by forking the repo and cloning locally:
 
-```
+```bash
 $ git clone https://github.com/{you}/bga-wingspan-scraper
 ```
 
-Then, 
+Then, install the dependencies:
+
+```bash
+$ npm install
+```
+
+## Working with git
+
+There's no way I can fit a whole git tutorial in here, so this just highlights a
+couple of key functionalities you'll need.
+
+First, always hack on a bugfix or feature in a new branch:
+
+```
+$ git checkout -b description-of-change
+```
+
+This makes it a lot simpler to get your repo fork up to date after `main`
+receives further commits.
+
+To bring your fork's `main` up to date, you first need to add the main repo as a
+new git remote (one-time task):
+
+```
+$ git remote add upstream https://github.com/bskinn/bga-wingspan-scraper
+```
+
+Then, any time you need to refresh the fork's `main`:
+
+```
+$ git fetch --all
+$ git checkout main
+$ git merge upstream/main   # (should merge without incident)
+$ git push                  # (should push to your fork without incident)
+```
+
+## Building
+
+### Dev Builds
+
+_(builds with source maps to allow in-browser debugging)_
+
+### Production Builds
+
+_(builds to mostly(?) minified source for smaller package size)_
+
+## Testing
+
+No automated tests are currently set up in the repo. In part, this is because
+the only real source of truth is scraping a Wingspan game that we've manually
+checked, and seeing if the data matches what we got before. _Maybe_ at some
+point this will be worth fully automating, but it seems unlikely.
+
+In the meantime, we do have some manually checked datasets available for the
+score-scraping functionality (but not yet the total game scraping functionality)
+that can be used for consistency testing:
+
+1. Look for a dataset in either `/data` or `/olddata_yyyymmdd` that has a `-ts-`
+   or a `-ref-` in the middle of it.
+   - The `tablenum` for that dataset is the first number in the filename
+2. Scrape the game at `https://boardgamearena.com/table?table=${tablenum}`.
+3. Open this [score output checker Google Colab notebook][checker colab]
+4. Paste the contents of the reference `.b64` data file into the definition for
+   `all_data1`.
+5. Paste the contents of the newly-scraped `.b64` data file into the definition
+   for `all_data2`.
+6. Run the entire notebook.
+
+If the score scraping is consistent, the notebook should report that the table
+IDs for the two datasets are the same, and that no data mismatch was found.
+
+## CHANGELOG
+
+The project
+[`CHANGELOG`](https://github.com/bskinn/bga-wingspan-scraper/blob/main/CHANGELOG.md)
+should be updated for the majority of contributions. No tooling is in place for
+automated collation of news items into `CHANGELOG`; all changes should be
+documented manually, directly in the `CHANGELOG`. Please follow the format
+currently in use.
+
+Any PR that touches the project code _must_ include a `CHANGELOG` entry. Other
+changes of note (packaging/build tooling, test/lint tooling/plugins, tool
+settings, etc.) may also warrant a `CHANGELOG` bullet, depending on the
+situation. When in doubt, ask!
+
+## License
 
-## Test Heading 2
+All code and documentation contributions will respectively take on the MIT
+License and CC BY 4.0 license of the project at large.
 
 [@btskinn]: https://twitter.com/btskinn
 [@btskinn@fosstodon.org]: https://fosstodon.org/@btskinn
+[arch]: ARCHITECTURE.md
+[checker colab]: https://colab.research.google.com/drive/1zS8b31zubwhNxfEV8egb_qrQIpfkRkd6?usp=sharing
 [downloading an installer]: https://nodejs.org/en/download
 [issue]: https://github.com/bskinn/sphobjinv/issues

README.md

@@ -4,35 +4,56 @@ game on [Board Game Arena].
 
 This code has been developed and tested using Firefox around v118-119.
 
+<!-- toc -->
 
+- [Installation](#installation)
+  * [Release Version](#release-version)
+  * [Latest Version](#latest-version)
+- [Usage](#usage)
+- [Output Data Format](#output-data-format)
 
-## Use Via Local Firefox Extension
+<!-- tocstop -->
 
-### How to Install
+## Installation
 
-1. Clone the repo.
-2. Open Firefox and navigate to `about:debugging`
-3. Select "This Firefox" from the sidebar
-4. Click `Load Temporary Add-on...`
-5. Browse to the repo root and select `manifest.json`
-   - Though, I think any file will work, you're really picking the directory
+You can either use a release version of the extension, or the latest version of
+the code in the repo.
 
-### How to Use
+### Release Version 
 
-1. Navigate to a Wingspan game replay
-   - A set of overlay buttons should appear at the bottom left of the browser
-     window
+1. Download the `.zip` file from the most recent [release].
+2. Open Firefox and navigate to `about:debugging`.
+3. Select "This Firefox" from the sidebar.
+4. Click `Load Temporary Add-on...`.
+5. Browse to and select the downloaded `.zip` file.
+
+### Latest Version
+
+1. Follow the [project setup] and [production build] instructions from
+   `CONTRIBUTING.md`.
+2. Open Firefox and navigate to `about:debugging`.
+3. Select "This Firefox" from the sidebar.
+4. Click `Load Temporary Add-on...`.
+5. Browse to and select `build-prod/manifest.json`.
+
+
+## Usage
+
+1. Navigate to a Wingspan game replay.
+   - A set of (currently crude) overlay buttons should appear at the bottom left
+     of the browser window.
 2. Click `Check Move List` and `Check Play Sequence` to be sure that the move
    context scraping is working as expected. Both should show popup boxes
    containing `true`
 3. Click `Scrape Scores`. The script will start advancing through the game and
    scraping the scores. Once complete, it will automatically trigger download of
    the data files.
 
-## Data Output
+## Output Data Format
 
-The `scrapeAndSave()` script should automatically offer for download the scraped
-score data using the default download method configured in Firefox's settings.
+The `Scrape Scores` functionality should automatically offer for download the
+scraped score data using the default download method configured in Firefox's
+settings.
 
 Two files should be downloaded: one plaintext JSON file, and one file containing
 a base64-encoded string. Both files contain the same data. To read the b64 data
@@ -45,6 +66,14 @@ scraped:
 <table_id>-YYYYMMDD_HHMMSS.<ext>
 ```
 
+If you wish, feel free to use this [Google Colab notebook][colab notebook] to
+create a plot of the game score results. Paste the contents of the `.b64` output
+file into the definition for `fullData` and run the entire notebook.
+
 *(needs schema of this JSON)*
 
 [board game arena]: https://boardgamearena.com
+[colab notebook]: https://colab.research.google.com/drive/1GiVKnavp4eZkOjkfGCuf6FaqlDpXI0U4?usp=sharing
+[production build]: CONTRIBUTING.md#production-builds
+[project setup]: CONTRIBUTING.md#project-setup
+[release]: https://github.com/bskinn/bga-wingspan-scraper/releases

package.json

@@ -4,16 +4,18 @@
   "description": "Firefox extension to scrape BGA Wingspan game replays",
   "private": true,
   "scripts": {
-    "format": "run-p format:code format:tocs",
+    "format": "run-s format:code format:tocs",
     "tsc": "npx tsc --noEmit",
     "build": "run-s dev:clean dev:build dev:assets dev:manifest",
     "build-prod": "run-s prod:clean prod:build prod:assets prod:manifest",
     "clean": "npm run dev:clean",
     "clean-all": "run-p dev:clean prod:clean dist:clean",
     "dist": "run-s build-prod dist:clean dist:pack",
     "format:code": "npx prettier -w .",
-    "format:tocs": "run-p format:toc:CONTRIBUTING",
+    "format:tocs": "run-p format:toc:*",
     "format:toc:CONTRIBUTING": "npx markdown-toc -i CONTRIBUTING.md",
+    "format:toc:ARCHITECTURE": "npx markdown-toc -i ARCHITECTURE.md",
+    "format:toc:README": "npx markdown-toc -i README.md",
     "dev:clean": "node -e \"fs = require('fs'); fs.rmSync('build-dev', {recursive: true, force: true})\"",
     "dev:build": "npx webpack --config webpack.config.dev.js",
     "dev:assets": "npx copyfiles assets/**/* build-dev",