feat(repo): add mascot doc and tweak doc files

waldronmatt · Apr 3, 2024 · 37d72fe · 37d72fe
1 parent 0fa22f6
commit 37d72fe
Show file tree

Hide file tree

Showing 7 changed files with 49 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,13 @@
-<img src="https://github.com/waldronmatt/groundwork/blob/main/docs/repo/assets/pnpm-nx-lerna-dragon-logo.png?raw=true" alt="blue dragon" width="384" height="384" />
-
 # groundwork
 
 Welcome to my personal monorepo, a curated collection of boilerplate projects and reusable configurations. This repository serves as my go-to resource for quickly setting up new projects and experimenting with emerging technologies. Whether you're a fellow developer or just curious, feel free to explore and utilize these setups.
 
+## Prerequisites
+
+For cloning, follow the directions to install [pnpm](docs/repo/SETUP.md#pnpm), [additional packages](docs/repo/SETUP.md#additional-packages), and [nx](docs/repo/SETUP.md#nx).
+
+For forking, follow all the directions found in the [setup](docs/repo/SETUP.md) page.
+
 ## Installation
 
 Install dependencies:
@@ -12,12 +16,6 @@ Install dependencies:
 pnpm i
 ```
 
-Install additional required dependencies
-
-```bash
-npx playwright install
-```
-
 ## Getting Started
 
 Run local development servers:
@@ -40,8 +38,6 @@ pnpm test
 
 Compile files and build bundle:
 
-**Note**: Run `pnpm clean` before `pnpm build` to clear `dist` output
-
 ```bash
 pnpm build
 ```
@@ -56,7 +52,7 @@ pnpm preview
 
 ## Additional Documentation
 
-Additional project setup, commands and documentation can be [found here](docs/repo/README.md).
+Additional documentation for this repo can be [found here](docs/repo/README.md).
 
 ## License
 

diff --git a/docs/repo/ARCHITECTURE.md b/docs/repo/ARCHITECTURE.md
@@ -54,7 +54,20 @@ For versioning, we have `excludeDependents` set to `true` in our `lerna` config.
 
 ## Package Testing
 
-Internal packages used in other packages are imported by referencing the `lib` / `src` subpath export and installed via `pnpm`'s `workspace:` protocol.
+Internal packages used in other packages are imported by referencing the `lib` / `src` subpath export and installed via `pnpm`'s `workspace:` protocol. An example subpath export setup for a package in this repo will typically look like this:
+
+`package.json`
+
+```json
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./*": "./dist/*",
+    "./src/*": "./lib/*"
+  },
+```
 
 For example, I have a react component library package that I reference in the storybook and vite-project apps. If I make updates to the react library, I want those changes to automatically refresh (hmr) in those apps. The `lib` / `src` subpath exports allow us to link to the source files so we can avoid rebuilding the component library to see changes.
 

diff --git a/docs/repo/COMMANDS.md b/docs/repo/COMMANDS.md
@@ -14,7 +14,7 @@ pnpm clean
 
 Delete workspace root `node_modules` and `pnpm-lock.yaml` files:
 
-**Note**: Follow the directions [here](docs/repo/SETUP.md#global-packages) to install `rimraf` globally so errors aren't thrown.
+**Note**: Follow the directions [here](docs/repo/SETUP.md#additional-packages) to install `rimraf` globally so errors aren't thrown.
 
 ```bash
 pnpm delete

diff --git a/docs/repo/MASCOT.md b/docs/repo/MASCOT.md
@@ -0,0 +1,9 @@
+# Logo
+
+![blue dragon](./assets/pnpm-nx-lerna-dragon-logo.png)
+
+I had some fun with chatgpt's dall-e and fed it logos of pnpm, nx, and lerna; the core software this monorepo uses to manage multiple apps and packages. After several prompts and tweaks, I settled on this image of a blue dragon.
+
+The dragon's inner body is constructed of tetris-like blocks that is inspired by pnpm's block-like logo. The blue color palette and wave-like patters on the dragon's scales and tail are inspired by nrwl's wave image embedded in the letter X. The dragon is inspired by lerna/lerna-lite's three-headed dragon.
+
+This fusion of elements in a single dragon symbolizes the cohesive strength and stability these tools provide in managing large-scale codebases.
diff --git a/docs/repo/README.md b/docs/repo/README.md
@@ -19,3 +19,7 @@
 [Setup](SETUP.md)
 
 [Syncpack Commands](SYNCPACK.md)
+
+## Other Documentation
+
+[Groundwork Mascot](MASCOT.md)
diff --git a/docs/repo/SETUP.md b/docs/repo/SETUP.md
@@ -4,20 +4,28 @@
 
 Follow the directions [here](https://pnpm.io/installation) to install pnpm.
 
-## Global Packages
+## Additional Packages
 
 Globally install the `rimraf` package via:
 
 ```bash
 pnpm i -g rimraf
 ```
 
+Install `playwright` browser binaries:
+
+```bash
+npx playwright install
+```
+
 ## Git Hooks
 
-Install husky and hooks in your repo for the first time:
+Install husky hooks:
+
+**Note**: `pnpm` should automatically run `prepare` when installing
 
 ```bash
-pnpm exec husky init
+pnpm prepare
 ```
 
 ## NX
@@ -62,7 +70,7 @@ Create a `security` PR label. Renovate will automatically create a PR and apply
 
 ## Kodiak
 
-Follow the directions [here](https://kodiakhq.com/docs/quickstart) to set up Kodiak.
+Follow the directions [here](https://kodiakhq.com/docs/quickstart) to set up Kodiak. Make sure to [configure GitHub branch protection](https://help.github.com/en/articles/configuring-protected-branches). Setup [required status checks](https://docs.github.com/en/github/administering-a-repository/enabling-required-status-checks) to prevent failing PRs from being merged.
 
 Create a `wip` PR label. When you set the `wip` label on a PR, Kodiak will not merge it.
 

diff --git a/docs/repo/TOOLS.md b/docs/repo/TOOLS.md
@@ -34,6 +34,8 @@
 
 [`commitizen`](https://github.com/commitizen/cz-cli): For enabling `cz-conventional-changelog` via the command line
 
+[`only-allow`](https://github.com/pnpm/only-allow): For forcing a specific package manager to be used on a project
+
 ## CICD
 
 [`github actions`](https://docs.github.com/en/actions): For CI/CD