feat: add codeowners (#386)

* Update CLI keywords * Add codeowners as a feature * Link back to repo * Add sauced.yml file * Change to .yaml * Reorganize pizza-cli structure * Fix path * Add tip to direct users to codeowners * Add docs for codeowners * Add info on codeowners action * Add pizza-action docs * Make action v2 * Add clarifications * Format file name Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Update docs/tools/pizza-cli/codeowners.md Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Format file name Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Add spaces to admonition Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Use backticks for formatting Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Add spaces to admonition Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Add spaces to admonition Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Add spaces to admonition again Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Add spaces to admonition Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Add spaces to admonition, last one Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com> * Add end of line --------- Co-authored-by: Ayu Adiati <45172775+adiati98@users.noreply.github.com>
open-sauced · Sep 6, 2024 · 5c72951 · 5c72951
1 parent a6d1bb2
commit 5c72951
Show file tree

Hide file tree

Showing 6 changed files with 251 additions and 16 deletions.
diff --git a/.github/workflows/pizza-action.yml b/.github/workflows/pizza-action.yml
@@ -0,0 +1,17 @@
+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/pizza-action@v2.0.0
+        with:
+          commit-and-pr: true
+
diff --git a/.sauced.yaml b/.sauced.yaml
@@ -0,0 +1,26 @@
+# 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.
+  brandonroberts:
+    - robertsbt@gmail.com
+  jpmcb:
+    - john@opensauced.pizza
+    - jpmmcbride@gmail.com
+  nickytonline:
+    - nick@nickyt.co
+    - nick@opensauced.pizza
+  bdougie:
+    - bdougie@users.noreply.github.com
+  zeucapua:
+    - coding@zeu.dev
+  bekahhw:
+    - BekahHW@users.noreply.github.com
+    - rhawrot@gmail.com
+  BekahHW:
+    - BekahHW@users.noreply.github.com
+  adiati98:
+    - adiati98@users.noreply.github.com
+
diff --git a/docs/tools/pizza-cli/codeowners.md b/docs/tools/pizza-cli/codeowners.md
@@ -0,0 +1,117 @@
+---
+id: codeowners
+title: "Pizza CLI Codeowners Command"
+sidebar_label: "Codeowners"
+keywords: 
+- "codeowners" 
+- "codeowners automation" 
+- "CLI codeowners" 
+---
+
+The `codeowners` command in the Pizza CLI is designed to automatically generate and manage CODEOWNERS files for your GitHub repositories. CODEOWNERS files are used to define individuals or teams responsible for code in a repository, which is useful for code review processes and maintaining code quality.
+
+Key benefits of using the codeowners command:
+
+- Automatically determines codeownership based on contribution history
+- Simplifies the process of keeping CODEOWNERS files up-to-date
+- Ensures that the right people are notified for code reviews
+- Helps in identifying subject matter experts for different parts of the codebase
+- Facilitates better project management and knowledge distribution
+
+To generate a CODEOWNERS file, you need to [install the Pizza CLI](pizza-cli.md) and run the `pizza generate codeowners` command in your terminal. However, before running the command, it's important to set up proper attribution for committers in a `.sauced.yaml` file.
+
+## Creating a `.sauced.yaml` file
+
+The `.sauced.yaml` file is necessary for mapping commit email addresses to GitHub usernames. However, it's important to be selective about who you include in this file. Not every contributor should be a codeowner.
+
+<details>
+<summary>Selecting appropriate codeowners</summary>
+
+When deciding who to include in your `.sauced.yaml` file, consider the following:
+
+1. **Team members**: Include active members of your organization who are responsible for maintaining the codebase.
+
+2. **Expertise**: Prioritize individuals with deep knowledge of specific areas of the codebase.
+
+3. **GitHub team members**: Include members of the GitHub teams associated with the repository.
+
+4. **Long-term contributors**: Consider long-standing contributors who have demonstrated commitment to the project.
+
+:::tip
+
+Be cautious about including external contributors. Only include those who have been vetted and are trusted to review and approve changes.
+
+:::
+
+Codeowners will be automatically requested for review on pull requests that modify code they own.
+</details>
+
+### Tips for identifying potential codeowners
+
+1. Review GitHub team memberships:
+   ```bash
+   gh api /orgs/{org}/teams/{team}/members --jq '.[].login'
+   ```
+   Replace `{org}` with your organization name and `{team}` with the team name.
+
+3. Review recent active contributors:
+   ```bash
+   git log --since='6 months ago' --pretty=format:'%an' | sort | uniq -c | sort -nr
+   ```
+   This lists active contributors in the last 6 months.
+
+### Mapping GitHub usernames to email addresses
+
+Mapping GitHub usernames to their corresponding email addresses is necessary for creating an accurate `.sauced.yaml` file. For contributors to your repository, you can use `git log` to find their email addresses:
+
+   ```bash
+   git log --author="GitHub_Username" --format='%ae' | sort -u
+   ```
+
+Replace `GitHub_Username` with the actual GitHub username. This command will show all email addresses used by that user in their commits to your repository.
+
+Alternatively, you can run the following command to get a list of your contributors' email addresses:
+
+   ```bash
+   git log --format='%ae' | sort -u
+   ```
+
+## Creating the `.sauced.yaml` file
+
+After identifying appropriate codeowners, create the `.sauced.yaml` file in your repository's root directory with the following structure:
+
+   ```yaml
+   attribution:
+     githubUsername1:
+       - user1@email.com
+       - user1@company.com
+     githubUsername2:
+       - user2@email.com
+   ```
+
+Only include the GitHub usernames and email addresses of the individuals you've identified as appropriate codeowners based on the considerations mentioned above.
+
+## Pizza CLI Codeowners Command
+
+To generate the CODEOWNERS file, you need to provide the path to your repository as an argument:
+
+```bash
+pizza generate codeowners /path/to/your/repo
+```
+
+If you're already in your repository's root directory, you can use:
+
+```bash
+pizza generate codeowners .
+```
+:::info
+
+- Ensure you have the necessary permissions to read the repository and write the CODEOWNERS file.
+- The command requires a `.sauced.yaml` file in the repository root for accurate attribution (as described in the previous section).
+- If you encounter any errors, double-check that you've provided the correct path to your repository.
+- 
+:::
+
+The codeowners command will analyze your repository's commit history and generate a CODEOWNERS file based on contributors' activity in the last 90 days.
+
+It is useful to keep this file up-to-date with the most recent codeowners. To automate this process, you can use the `pizza-action`. To learn more about this GitHub action, go to the [pizza-action docs](pizza-action.md) or visit [the repository](https://github.com/open-sauced/pizza-action).
diff --git a/docs/tools/pizza-cli/pizza-action.md b/docs/tools/pizza-cli/pizza-action.md
@@ -0,0 +1,54 @@
+---
+id: pizza-action
+title: "Pizza CLI Action"
+sidebar_label: "Pizza Action"
+keywords: 
+- "codeowners" 
+- "codeowners automation" 
+- "CLI codeowners" 
+- "GitHub Actions"
+- "Codeowners GitHub Action"
+---
+
+To automatically update your CODEOWNERS file every week, you can use the OpenSauced Pizza GitHub Action. This action runs the Pizza CLI in a GitHub Actions workflow.
+
+To set up the action:
+
+1. Create a new file in your repository at `.github/workflows/pizza-action.yml`
+2. Add the following content to the file:
+
+```yaml
+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/pizza-action@v1.0.0
+        with:
+          # optional and false by default
+          commit-and-pr: "true"
+```
+
+This workflow will run the Pizza CLI's `generate codeowners ./` command once a week, ensuring your CODEOWNERS file stays up-to-date.
+
+:::info
+
+- The action uses `fetch-depth: 0` to ensure all historical commits are available for analysis.
+- The `commit-and-pr` input determines whether to commit changes and create a pull request (default is `false`).
+- You can customize the `pizza-args` input to pass different arguments to the Pizza CLI (default is `generate codeowners ./`).
+
+:::
+
+For more information about the Pizza Action, visit the [open-sauced/pizza-action repository](https://github.com/open-sauced/pizza-action).
+
+### Troubleshooting
+
+If you encounter the error "pull request create failed: GraphQL: GitHub Actions is not permitted to create or approve pull requests (createPullRequest)", go to your repository settings under the Actions section and check "Allow GitHub Actions to create and approve pull requests".
diff --git a/docs/tools/pizza-cli.md → docs/tools/pizza-cli/pizza-cli.md b/docs/tools/pizza-cli.md → docs/tools/pizza-cli/pizza-cli.md
@@ -6,30 +6,38 @@ keywords:
 - "introduction to the pizza cli" 
 - "Pizza CLI Overview" 
 - "Command Line Interface Introduction" 
-- "CLI Basics" 
-- "Pizza Command Line Tool" 
+- "CLI Basics for GitHub Insights" 
 - "CLI Usage Guide" 
 - "Pizza CLI Commands" 
 - "Introduction to Command-Line Interfaces" 
 - "Command Line Tool Features" 
-- "CLI for Pizza Enthusiasts" 
-- "Pizza Ordering CLI" 
-- "Getting Started with Pizza CLI" 
+- "Getting Started with the CLI for GitHub Insights" 
 ---
 
-## The OpenSauced Pizza CLI
-
 The OpenSauced Pizza CLI is a command-line utility designed specifically for OpenSauced. It provides a comprehensive set of functionalities that make it easier for users to gain insights and metrics and manage various tasks related to open source projects through OpenSauced.
 
 Beyond just code commits, the pizza CLI reports on different ways individuals contribute to the open source ecosystem through community engagement, issue reporting, blog post writings, or pull request creations.
 
+:::info
+
+To access the CLI repo, visit the [pizza/cli GitHub repository](https://github.com/open-sauced/pizza-cli).
+
+:::
+
 ## Key Features
 
 - **Bake**: Seamlessly source git commits into OpenSauced with the metaphorical 'oven' of technology.
 - **Insights**: Dive deep into data about git contributors, repositories, users, and pull requests.
 - **Repo-query**: Get your questions about any GitHub repository answered.
 - **Show**: Visualize the metrics of a repository, providing a holistic view of its health and activity.
 - **Login**: Securely log into the application via GitHub, ensuring a streamlined and safe experience.
+- **Codeowners**: Generate and manage CODEOWNERS files for your repositories.
+
+:::tip
+
+For more on the Codeowners command, visit the [Codeowners page](codeowners.md)
+
+:::
 
 ## Installation and Instructions
 
@@ -54,15 +62,19 @@ The pizza CLI provides multiple installation methods to cater to the varied pref
   ```bash
   curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh
   ```
-
-  ⚠️ **Warning**: Piping scripts directly from the web to your shell can be risky. Always ensure you trust the source. For a safer approach, download, inspect, and then execute the following commands:
-
-  ```bash
-  curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh > install.sh
-  vim install.sh
-  ./install.sh
+  :::danger
+
+  Piping scripts directly from the web to your shell can be risky. Always ensure you trust the source. 
+
+  :::
+
+   For a safer approach, download, inspect, and then execute the following commands:
+
+     ```bash
+    curl -fsSL https://raw.githubusercontent.com/open-sauced/pizza-cli/main/install.sh > install.sh
+    vim install.sh
+    ./install.sh
   ```
-
 - **Manual build and install**: For those who like a hands-on approach.
 
   ```bash

diff --git a/sidebars.js b/sidebars.js
@@ -87,7 +87,16 @@ module.exports = {
       collapsed: true,
       items: [
         "tools/hot-opensauced",
-        "tools/pizza-cli",
+        {
+          type: "category",
+          label: "Pizza CLI",
+          collapsed: true,
+          items: [
+            "tools/pizza-cli/pizza-cli",
+            "tools/pizza-cli/codeowners",
+            "tools/pizza-cli/pizza-action",
+          ],
+        },
         {
           type: "category",
           label: "Chrome Extension Usage",