From 99328aaa322b6dc4abe3f1933b6e77ffedecb355 Mon Sep 17 00:00:00 2001 From: John McBride Date: Fri, 13 Sep 2024 11:02:13 -0600 Subject: [PATCH] feat: Update README docs (#186) Signed-off-by: John McBride --- README.md | 265 ++++++++++++++++++++++++++++++++++---------------- npm/README.md | 170 +++++++++++++++++++++++--------- 2 files changed, 306 insertions(+), 129 deletions(-) diff --git a/README.md b/README.md index b342b0f..b590634 100644 --- a/README.md +++ b/README.md @@ -2,15 +2,34 @@

🍕 Pizza CLI 🍕

A Go command line interface for managing code ownership and project insights with OpenSauced! +
+
+ Watch the overview video 👇 +

CODEOWNERS demo -
+
+ GitHub code size in bytes + + GitHub issues + + + GitHub Release + + + Twitter + + + + +
+ # 📦 Install #### Homebrew @@ -25,29 +44,13 @@ brew install open-sauced/tap/pizza npm i -g pizza ``` -### Docker - -```sh -$ docker run ghcr.io/open-sauced/pizza-cli:latest -``` - -For commands that require access to your file system (like `generate codeowners`), ensure -you pass a volume to the docker container: +You can also use `npx` to run one-off commands without installing anything: ```sh -$ docker run -v /local/path:/container/path ghcr.io/open-sauced/pizza-cli:latest \ - generate codeowners /container/path +npx pizza@latest generate codeowners . ``` -For example, to mount your entire home directory (which may include a `.sauced.yaml` file -alongside the project you want to generate a `CODEOWNERS` file for): - -```sh -$ docker run -v ~/:/app ghcr.io/open-sauced/pizza-cli:latest \ - codeowners /app/workspace/gopherlogs -c /app/.sauced.yaml -``` - -### Go install +#### Go install Using the Go tool-chain, you can install the binary directly: @@ -55,10 +58,11 @@ Using the Go tool-chain, you can install the binary directly: $ go install github.com/open-sauced/pizza-cli@latest ``` -Warning! You should have the `GOBIN` env var setup to point to a persistent -location in your `PATH`. After Go 1.16, this defaults to `GOPATH[0]/bin`. +> [!WARNING] +> Warning! You should have the `GOBIN` env var setup to point to a persistent +> location in your `PATH`. After Go 1.16, this defaults to `GOPATH[0]/bin`. -### Manual install +#### Manual install Download a pre-built artifact from [the GitHub releases](https://github.com/open-sauced/pizza-cli/releases): @@ -71,7 +75,7 @@ $ chmod +x ~/Downloads/pizza-linux-arm64 $ mv ~/Downloads/pizza-linux-arm64 /usr/local/share/bin/pizza ``` -#### Direct script install +#### Script install ```sh curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh | sh @@ -95,117 +99,210 @@ your system's `$PATH`. > ./install.sh > ``` -#### Manual build +# 🐳 Docker -Clone this repository. Then, using the Go tool-chain, you can build a binary: +Use the container image of the CLI for use in CI/CD or automation: +```sh +$ docker run ghcr.io/open-sauced/pizza-cli:latest ``` -$ go build -o build/pizza main.go + +For commands that require access to your file system (like `generate codeowners`), ensure +you pass a volume to the docker container: + +```sh +$ docker run -v /local/path:/container/path ghcr.io/open-sauced/pizza-cli:latest \ + generate codeowners /container/path ``` -Warning! There may be unsupported features, breaking changes, or experimental -patches on the tip of the repository. Go and build with caution! +For example, to mount your entire home directory (which may include a `~/.sauced.yaml` file +alongside the project you want to generate a `CODEOWNERS` file for): + +```sh +$ docker run -v ~/:/app ghcr.io/open-sauced/pizza-cli:latest \ + codeowners /app/workspace/gopherlogs -c /app/.sauced.yaml +``` + +# 🍕 Pizza Action + +Use [the Pizza GitHub Action](https://github.com/open-sauced/pizza-action) for running `pizza` operations in GitHub CI/CD, +like automated `CODEOWNERS` updating and pruning: + +```yaml +jobs: + pizza-action: + runs-on: ubuntu-latest + steps: + - name: Pizza Action + uses: open-sauced/pizza-action@v2 + with: + # Optional: Whether to commit and create a PR for "CODEOWNER" changes + commit-and-pr: "true" + # Optional: Title of the PR for review by team + pr-title: "chore: update repository codeowners" +``` + +# 📝 Docs + +- [Pizza.md](./docs/pizza.md): In depth docs on each command, option, and flag. +- [OpenSauced.pizza/docs](https://opensauced.pizza/docs/tools/pizza-cli/): Learn + how to use the Pizza command line tool and how it works with the rest of the OpenSauced + ecosystem. # ✨ Usage ## Codeowners generation -Use the `codeowners` command to generate an `OWNERS` file or GitHub style `CODEOWNERS` file. +Use the `codeowners` command to generate a GitHub style `CODEOWNERS` file or a more agnostic `OWNERS` file. This can be used to granularly define what experts and entities have the most context and knowledge on certain parts of a codebase. +It's expected that there's a `.sauced.yaml` config file in the given path or in +your home directory (as `~/.sauced.yaml`): + +```sh +pizza generate codeowners /path/to/local/git/repo +``` + +Running this command will iterate the git ref-log to determine who to set as a code +owner based on the number of lines changed for that file within the given time range. +The first owner is the entity with the most lines changed. This command uses a `.sauced.yaml` configuration +to attribute emails in commits with the given entities in the config (like GitHub usernames or teams). +See [the section on the configuration schema for more details](#-configuration-schema) + +### 🚀 New in v1.4.0: Generate Config + +The `pizza generate config` command has been added to help you create `.sauced.yaml` configuration files for your projects. +This command allows you to generate configuration files with various options: + +```sh +pizza generate config /path/to/local/git/repo ``` -❯ pizza generate codeowners -h -Generates a CODEOWNERS file for a given git repository. This uses a ~/.sauced.yaml -configuration to attribute emails with given entities. +This command will iterate the git ref-log and inspect email signatures for commits +and, in interactive mode, ask you to attribute those users with GitHub handles. Once finished, the resulting +`.sauced.yaml` file can be used to attribute owners in a `CODEOWNERS` file during `pizza generate codeowners`. -The generated file specifies up to 3 owners for EVERY file in the git tree based on the -number of lines touched in that specific file over the specified range of time. +#### Flags: + +- `-i, --interactive`: Enter interactive mode to attribute each email manually +- `-o, --output-path string`: Set the directory for the output file +- `-h, --help`: Display help for the command + +#### Examples: + +1. Generate a config file in the current directory: + ```sh + pizza generate config ./ + ``` + +2. Generate a config file interactively: + ```sh + pizza generate config ./ -i + ``` -Usage: - pizza generate codeowners path/to/repo [flags] +3. Generate a config file from the current directory and place resulting `.sauced.yaml` in a specific output directory: + ```sh + pizza generate config ./ -o /path/to/directory + ``` -Flags: - --owners-style-file Whether to generate an agnostic OWNERS style file. - -h, --help help for codeowners - -r, --range int The number of days to lookback (default 90) +## OpenSauced Contributor Insight from `CODEOWNERS` -Global Flags: - --beta Shorthand for using the beta OpenSauced API endpoint ("https://beta.api.opensauced.pizza"). - Supersedes the '--endpoint' flag - -c, --config string The codeowners config (default ".sauced.yaml") - --disable-telemetry Disable sending telemetry data to OpenSauced - -e, --endpoint string The API endpoint to send requests to (default "https://api.opensauced.pizza") - -l, --log-level string The logging level. Options: error, warn, info, debug (default "info") - -o, --output string The formatting for command output. One of: (table, yaml, csv, json) (default "table") - --tty-disable Disable log stylization. Suitable for CI/CD and automation +You can create an [OpenSauced Contributor Insight](https://opensauced.pizza/docs/features/contributor-insights/) +from a local `CODEOWNERS` file: + +``` +pizza generate insight /path/to/repo/with/CODEOWNERS/file ``` -## Configuration +This will parse the `CODEOWNERS` file and create a Contributor Insight on the OpenSauced platform. +This allows you to track insights and metrics for those codeowners, powered by OpenSauced. + +## Insights + +You can get metrics and insights on repositories, contributors, and more: + +``` +pizza insights [sub-command] +``` + +This powerful command lets you compose many metrics and insights together, all +powered by OpenSauced's API. Use the `--output` flag to output the results as yaml, json, csv, etc. + +# 🎷 Configuration schema ```yaml # Configuration for attributing commits with emails to individual entities. # Used during "pizza generate codeowners". attribution: - # Keys can be GitHub usernames. For the "--github-codeowners" style codeowners - # generation, these keys must be valid GitHub usernames. + # Keys can be GitHub usernames. jpmcb: - # List of emails associated with the given entity. + # List of emails associated with the given GitHub login. # The commits associated with these emails will be attributed to - # the entity in this yaml map. Any number of emails may be listed. + # this GitHub login in this yaml map. Any number of emails may be listed. - john@opensauced.pizza - hello@johncodes.com - # Entities may also be GitHub teams. + # Keys may also be GitHub teams. This is useful for orchestrating multiple + # people to a sole GitHub team. open-sauced/engineering: - john@opensauced.pizza - other-user@email.com - other-user@no-reply.github.com - # They can also be agnostic names which will land as keys in OWNERS files + # Keys can also be agnostic names which will land as keys in "OWNERS" files + # when the "--owners-style-file" flag is set. John McBride - john@opensauced.pizza + +# Used during codeowners generation: if there are no code owners found +# for a file within the time range, the list of fallback entities +# will be used +attribution-fallback: + - open-sauced/engineering + - some-other-github-login ``` -### 🚀 New in v1.4.0: Generate Config +# 🚜 Development -The `pizza generate config` command has been added to help you create configuration files for your projects. This command allows you to generate configuration files with various options: +### Requirements -```sh -pizza generate config [flags] -``` +There are a few things you'll need to get started: -#### Flags: +- The [1.22 `go` programming language](https://go.dev/doc/install) toolchain and dev environment (for example, the [VScode Go plugin](https://code.visualstudio.com/docs/languages/go) is very good). +- The [`just` command runner](https://github.com/casey/just) for easy operations -- `-i, --interactive`: Enter interactive mode to attribute each email manually -- `-o, --output-path string`: Set the directory for the output file -- `-h, --help`: Display help for the command +### Building -#### Examples: +Clone this repository. Then, using the Go tool-chain, you can build a binary: -1. Generate a config file in the current directory: - ```sh - pizza generate config - ``` +``` +go build -o build/pizza main.go +``` -2. Generate a config file interactively: - ```sh - pizza generate config -i - ``` +> [!WARNING] +> There may be unsupported features, breaking changes, or experimental +> patches on the tip of the repository. Go and build with caution! -3. Generate a config file in a specific directory: - ```sh - pizza generate config -o /path/to/directory - ``` +There are a number of `just` convinence commands for building with injected buildtime variables +and targeting other architectures and operating systems. -# 🚜 Development +``` +just build +``` +``` +just build-all +``` -### 🔨 Requirements +### Dev operations -There are a few things you'll need to get started: +There are a number of useful `just` commands that should be used during development: +- `just lint` will us Golangci-lint to lint the Go code +- `just clean` removes build artifacts from `build/` +- `just test` runs the unit and e2e tests +- `just format` uses goimports to format code +- ... and many more! -- The [1.22 `go` programming language](https://go.dev/doc/install) toolchain and dev environment (for example, the [VScode Go plugin](https://code.visualstudio.com/docs/languages/go) is very good). -- The [`just` command runner](https://github.com/casey/just) for easy operations +Check `just help` to get a full list of utility dev commands! diff --git a/npm/README.md b/npm/README.md index 48777e0..8f4bd4d 100644 --- a/npm/README.md +++ b/npm/README.md @@ -6,49 +6,25 @@

-

+

GitHub code size in bytes GitHub issues - - GitHub Release - - - Discord + + GitHub Release Twitter -

- -``` -❯ pizza - -A command line utility for insights, metrics, and all things OpenSauced - -Usage: - pizza [flags] - -Available Commands: - generate Generate configurations and codeowner files - bake Use a pizza-oven to source git commits into OpenSauced - completion Generate the autocompletion script for the specified shell - help Help about any command - login Log into the CLI application via GitHub - repo-query Ask questions about a GitHub repository - -Flags: - -h, --help help for pizza - -Use "pizza [command] --help" for more information about a command. -``` + + + +
--- -### 📦 Install - -There are several methods for downloading and installing the `pizza` CLI: +# 📦 Install #### Homebrew @@ -62,27 +38,72 @@ brew install open-sauced/tap/pizza npm i -g pizza ``` -#### Direct script install +You can also use `npx` to run one-off commands without installing anything: ```sh -curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh | sh +npx pizza@latest generate codeowners . +``` + +# 🍕 Pizza Action + +Use [the Pizza GitHub Action](https://github.com/open-sauced/pizza-action) for running `pizza` operations in GitHub CI/CD, +like automated `CODEOWNERS` updating and pruning: + +```yaml +jobs: + pizza-action: + runs-on: ubuntu-latest + steps: + - name: Pizza Action + uses: open-sauced/pizza-action@v2 + with: + # Optional: Whether to commit and create a PR for "CODEOWNER" changes + commit-and-pr: "true" + # Optional: Title of the PR for review by team + pr-title: "chore: update repository codeowners" ``` -This is a convenience script that can be downloaded from GitHub directly and -piped into `sh` for conveniently downloading the latest GitHub release of the -`pizza` CLI. +# 📝 Docs + +- [Pizza.md](./docs/pizza.md): In depth docs on each command, option, and flag. +- [OpenSauced.pizza/docs](https://opensauced.pizza/docs/tools/pizza-cli/): Learn + how to use the Pizza command line tool and how it works with the rest of the OpenSauced + ecosystem. + +# ✨ Usage + +## Codeowners generation + +Use the `codeowners` command to generate a GitHub style `CODEOWNERS` file or a more agnostic `OWNERS` file. +This can be used to granularly define what experts and entities have the +most context and knowledge on certain parts of a codebase. -Once download is completed, you can move the binary to a convenient location in -your system's `$PATH`. +It's expected that there's a `.sauced.yaml` config file in the given path or in +your home directory (as `~/.sauced.yaml`): + +```sh +pizza generate codeowners /path/to/local/git/repo +``` + +Running this command will iterate the git ref-log to determine who to set as a code +owner based on the number of lines changed for that file within the given time range. +The first owner is the entity with the most lines changed. This command uses a `.sauced.yaml` configuration +to attribute emails in commits with the given entities in the config (like GitHub usernames or teams). +See [the section on the configuration schema for more details](#-configuration-schema) ### 🚀 New in v1.4.0: Generate Config -The `pizza generate config` command has been added to help you create configuration files for your projects. This command allows you to generate configuration files with various options: +The `pizza generate config` command has been added to help you create `.sauced.yaml` configuration files for your projects. +This command allows you to generate configuration files with various options: ```sh -pizza generate config [flags] +pizza generate config /path/to/local/git/repo ``` +This command will iterate the git ref-log and inspect email signatures for commits +and, in interactive mode, ask you to attribute those users with GitHub handles. Once finished, the resulting +`.sauced.yaml` file can be used to attribute owners in a `CODEOWNERS` file during `pizza generate codeowners`. + #### Flags: - `-i, --interactive`: Enter interactive mode to attribute each email manually @@ -93,15 +114,74 @@ pizza generate config [flags] 1. Generate a config file in the current directory: ```sh - pizza generate config + pizza generate config ./ ``` 2. Generate a config file interactively: ```sh - pizza generate config -i + pizza generate config ./ -i ``` -3. Generate a config file in a specific directory: +3. Generate a config file from the current directory and place resulting `.sauced.yaml` in a specific output directory: ```sh - pizza generate config -o /path/to/directory + pizza generate config ./ -o /path/to/directory ``` + +## OpenSauced Contributor Insight from `CODEOWNERS` + +You can create an [OpenSauced Contributor Insight](https://opensauced.pizza/docs/features/contributor-insights/) +from a local `CODEOWNERS` file: + +``` +pizza generate insight /path/to/repo/with/CODEOWNERS/file +``` + +This will parse the `CODEOWNERS` file and create a Contributor Insight on the OpenSauced platform. +This allows you to track insights and metrics for those codeowners, powered by OpenSauced. + +## Insights + +You can get metrics and insights on repositories, contributors, and more: + +``` +pizza insights [sub-command] +``` + +This powerful command lets you compose many metrics and insights together, all +powered by OpenSauced's API. Use the `--output` flag to output the results as yaml, json, csv, etc. + +# 🎷 Configuration schema + +```yaml +# Configuration for attributing commits with emails to individual entities. +# Used during "pizza generate codeowners". +attribution: + + # Keys can be GitHub usernames. + jpmcb: + + # List of emails associated with the given GitHub login. + # The commits associated with these emails will be attributed to + # this GitHub login in this yaml map. Any number of emails may be listed. + - john@opensauced.pizza + - hello@johncodes.com + + # Keys may also be GitHub teams. This is useful for orchestrating multiple + # people to a sole GitHub team. + open-sauced/engineering: + - john@opensauced.pizza + - other-user@email.com + - other-user@no-reply.github.com + + # Keys can also be agnostic names which will land as keys in "OWNERS" files + # when the "--owners-style-file" flag is set. + John McBride + - john@opensauced.pizza + +# Used during codeowners generation: if there are no code owners found +# for a file within the time range, the list of fallback entities +# will be used +attribution-fallback: + - open-sauced/engineering + - some-other-github-login +```