doc: update READMEs and add two scripts in package.json (#70)

Signed-off-by: Tierney Cyren <[email protected]>

README.md

@@ -4,12 +4,32 @@ This is a repository of GitHub OSPO Actions that pull stats that we can report o
 
 ## Actions
 
-- Monthly Contributors: Produces information about the contributors, monthly, for our Twilio's public GitHub organizations.
-- Issue Metrics: Gather metrics on Issues, PRs, and Discussions such as time to first response, count of issues opened, closed, and so on. Currently limited to twilio-node and sendgrid-nodejs as a trial.
-- Stale Repo Watchtower: A monitor that watches for stale repositories so we can act on them, if needed.
-- Retro Generator: A tool to generate a retro document from GitHub issues and PRs across Twilio's public GitHub organizations.
+- [Monthly Contributors](./reports/contributors/): Produces information about the contributors, monthly, for our Twilio's public GitHub organizations.
+- [Issue Metrics](./reports/metrics/): Gather metrics on Issues, PRs, and Discussions such as time to first response, count of issues opened, closed, and so on. Currently limited to twilio-node and sendgrid-nodejs as a trial.
+- [Stale Repository Watchtower](./reports/watchtower/): A monitor that watches for stale repositories so we can act on them, if needed.
+- [Retro Generator](./reports/retros/): A tool to generate a retro document from GitHub issues and PRs across Twilio's public GitHub organizations.
 
+## Maintenance
 
-## Content
+The majority of the "work" of this repository exists in `./.github/workflows/` and runs on many crons. Additionally, there's some supporitng scripting in `./utilities` that allows us to shift to be file based and leverage git to manage historical context, rather than using issues.
 
-Currently content exists in two forms - issues and markdown files. This is a result of the actions used, not becuase one form is superior over the other. The formats will likely be merged in the future.
+The crons have been intentionally spaced out because we pretty consistently run into GitHub's secondary rate limtis, especially when submitting a PR with the `gr2m/create-or-update-pull-request` action running _after_ the OSPO actions built by GitHub.
+
+For the retros, we specifically leverage [`cutenode/retrogen`](https://github.com/cutenode/retrogen) to poll the GitHub API and then write a markdown file. This tool isn't perfect, so if there are issues with it, consider checking back in that repository for fixes/issues.
+
+### production npm scripts
+
+This repository heavily relies on npm scripts as a way to create short-hand instructions that we can use in the GitHub Actions. Here's an overview of the namespaces of the production npm scripts:
+
+- `convert` scripts use utilities in `./utilities` to convert data from the OSPO Actions from GitHub from a temporary markdown file to a permanent one.
+- `retro` scripts generate retros using `cutenode/retrogen` with the scripts in `./utilities/retros`.
+
+### maintainer npm scripts
+
+In addition to the npm scripts that we use for "production", there's also a handful of scripts that we use for maintenance and development. Here's a quick rundown:
+
+- `npm run biome:format`: use biome to format the code.
+- `npm run biome:lint`: use biome to lint the code.
+- `biome:lint:apply`: use biome to apply the linting fixes. I believe this is being changed in newer versions of biome to use `write` rather than `apply`, and may need to be adjusted soon.
+- `npm run updates:check`: check for updates to dependencies using `npx` and `npm-check-updates`.
+- `npm run updates:apply`: apply updates to dependencies using `npx` and `npm-check-updates`, passing the `-u` flag to `npm-check-updates`.

package.json

@@ -30,7 +30,9 @@
 		"retro:twilio": "node utilities/retros/twilio.js",
 		"retro:twilio-labs": "node utilities/retros/twilio-labs.js",
 		"retro:twilio-samples": "node utilities/retros/twilio-samples.js",
-		"retro:sendgrid": "node utilities/retros/sendgrid.js"
+		"retro:sendgrid": "node utilities/retros/sendgrid.js",
+		"updates:check": "npx npm-check-updates",
+		"updates:apply": "npx npm-check-updates -u"
 	},
 	"author": "Tierney Cyren <[email protected]> (https://twilio.com)",
 	"license": "MIT",

reports/contributors/README.md

@@ -1,3 +1,19 @@
 # Contributor Reports
 
-The contents of this directory are generated by a set of automation so we can better report on our open source repositories.
+The contents of this directory are generated by a set of automations so we can better report on our open source repositories. The automations can be found in the [GitHub Actions](../../.github/workflows) directory, and are all prefixed with `contributors-`.
+
+## How to Read Contributor Reports
+
+Contributor reports consist of a few distinct parts:
+
+- Metadata
+  - Date range: The range of dates covered by the report.
+  - Organiation: The GitHub organization that the report is for.
+  - Total Contributors: The total number of contributors during the date range.
+  - Total Contributions: The total number of contributions during the date range.
+  - % New Contributors: The percentage of contributors who are new during the date range.
+- Data
+  - Username: The GitHub username of the contributor.
+  - Contribution Count: The number of contributions made by the contributor during the date range.
+  - New Contributor: A boolean indicating if the contributor is new during the date range.
+  - Commits: Link to per-repository commit list, scoped to the the specified date range.

utilities/README.md

@@ -0,0 +1,9 @@
+# Omnioculus Utilities
+
+This directory contains utilities that are used by Omnioculus. Here's a quick rundown of each utility:
+
+- `/contributors`: each of the files in this directory converts the output of the [`github/contributors`](https://github.com/github/contributors) action into a markdown format that we can submit a Pull Request for with the [`create-or-update-pull-request-action`](https://github.com/gr2m/create-or-update-pull-request-action) action.
+- `/helpers`: this directory contains a helper tool that converts the output from the OSPO GitHub Actions into a file so we can PR it, instead of creating an issue with it (as GitHub's team defaults to).
+- `/metrics`: each of the files in this directory converts the output of [`github/issue-metrics`](https://github.com/github/issue-metrics) action for one of the repositories we're tracking into a markdown format that we can submit a Pull Request for with the [`create-or-update-pull-request-action`](https://github.com/gr2m/create-or-update-pull-request-action) action.
+- `/retros`: each of the files in this directory creates a retro from the [`cutenode/retrogen`](https://github.com/github/contributors) library, outputting a markdown report.
+- `/watchtower`: scripts to convert watchtower reports from the [`github/stale-repo`](https://github.com/github/stale-repos) action for one of the repositories we're tracking into a markdown format that we can submit a Pull Request for with the [`create-or-update-pull-request-action`](https://github.com/gr2m/create-or-update-pull-request-action) action.