Skip to content

Latest commit

 

History

History
380 lines (285 loc) · 12.2 KB

README.md

File metadata and controls

380 lines (285 loc) · 12.2 KB
Raw

🍕 Pizza CLI 🍕

A Go command line interface for managing code ownership and project insights with OpenSauced!

Watch the overview video 👇

CODEOWNERS demo

📦 Install

Homebrew

brew install open-sauced/tap/pizza

NPM

npm i -g pizza

You can also use npx to run one-off commands without installing anything:

npx pizza@latest generate codeowners .

Go install

Using the Go tool-chain, you can install the binary directly:

$ go install github.com/open-sauced/pizza-cli@latest

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

Download a pre-built artifact from the GitHub releases:

# Make the binary executable
$ chmod +x ~/Downloads/pizza-linux-arm64

# Move the binary into a location in the PATH
# Warning: the location where you drop the binary may differ!
$ mv ~/Downloads/pizza-linux-arm64 /usr/local/share/bin/pizza

Script install

curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh | sh

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.

Once download is completed, you can move the binary to a convenient location in your system's $PATH.

Warning

It's probably not advisable to pipe scripts from GitHub directly into a command line interpreter! If you do not fully trust the source, first download the script, inspect it manually to ensure integrity, and then run it:

curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh > install.sh
vim install.sh
./install.sh

🐳 Docker

Use the container image of the CLI for use in CI/CD or automation:

$ 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:

$ docker run -v /local/path:/container/path ghcr.io/open-sauced/pizza-cli:latest \
    generate codeowners /container/path

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):

$ 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 for running pizza operations in GitHub CI/CD, like automated CODEOWNERS updating and pruning:

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: In depth docs on each command, option, and flag.
  • OpenSauced.pizza/docs: Learn how to use the Pizza command line tool and how it works with the rest of the OpenSauced ecosystem.

🚀 Quickstart

Get up and running with the Pizza CLI in minutes using npx:

  1. Ensure you have Node.js installed

    Pizza CLI can be run using npx, which comes with Node.js. If you don't have Node.js installed, download it from nodejs.org.

    NOTE For other installation methods, see the Install section.

  2. Generate a configuration file

    Navigate to your project directory and run:

    npx pizza@latest generate config ./ -i

    This will create a .sauced.yaml file, interactively prompting you to attribute commit emails to GitHub handles.

  3. Generate CODEOWNERS file

    In your project directory, run:

    npx pizza@latest generate codeowners ./

    This will create a CODEOWNERS file based on your project's git history and the .sauced.yaml configuration.

  4. Create OpenSauced Contributor Insight

    After generating the CODEOWNERS file, you can create an OpenSauced Contributor Insight:

    npx pizza@latest generate insight .

  5. Explore repository insights Get metrics and insights for your repository:

    npx pizza@latest insights repositories your-username/your-repo

  6. Set up automated CODEOWNERS updates (Optional) Add the Pizza GitHub Action to your repository to automate CODEOWNERS updates:

    # In .github/workflows/pizza-action.yml
name: OpenSauced Pizza Action
 on:
   schedule:
     # Run once a week on Sunday at 00:00 UTC
     - cron: "0 0 * * 0"
   workflow_dispatch: # Allow manual triggering

 jobs:
   pizza-action:
     runs-on: ubuntu-latest
     steps:
       - name: Pizza Action
         uses: open-sauced/[email protected]
         with:
           # optional and default is "latest". Add this parameter if you want to use a specific version, e.g. v2.0.0
           cli-version: "v2.2.0"
           # optional and false by default. Set this to true if you want to have a pull request for the changes created automatically.
           commit-and-pr: "true"
           # optional
           pr-title: "chore: update repository codeowners"

Now you're ready to leverage the Pizza CLI for managing code ownership and getting project insights with OpenSauced!

Note Using npx pizza@latest ensures you're always running the most recent version of Pizza CLI. If you prefer to use a specific version, you can replace @latest with a version number, e.g., npx [email protected].

✨ 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.

It's expected that there's a .sauced.yaml config file in the given path or in your home directory (as ~/.sauced.yaml):

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

🚀 New in v2.0.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:

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
  • -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:

    pizza generate config ./

  2. Generate a config file interactively:

    pizza generate config ./ -i

  3. Generate a config file from the current directory and place resulting .sauced.yaml in a specific output directory:

    pizza generate config ./ -o /path/to/directory

OpenSauced Contributor Insight from CODEOWNERS

You can create an OpenSauced Contributor Insight 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

# 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.
    - [email protected]
    - [email protected]

  # Keys may also be GitHub teams. This is useful for orchestrating multiple
  # people to a sole GitHub team.
  open-sauced/engineering:
    - [email protected]
    - [email protected]
    - [email protected]

  # Keys can also be agnostic names which will land as keys in "OWNERS" files
  # when the "--owners-style-file" flag is set.
  John McBride
    - [email protected]

# 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

🚜 Development

Requirements

There are a few things you'll need to get started:

Building

Clone this repository. Then, using the Go tool-chain, you can build a binary:

go build -o build/pizza main.go

Warning

There may be unsupported features, breaking changes, or experimental patches on the tip of the repository. Go and build with caution!

There are a number of just convinence commands for building with injected buildtime variables and targeting other architectures and operating systems.

just build

just build-all

Dev operations

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!

Check just help to get a full list of utility dev commands!