chore: update codeowners to latest version (#390)

* Restructure codeowners to reduce noise * Add fallback attribution * Remove extra bullet * Add EOL char back in Co-authored-by: Nick Taylor <[email protected]> --------- Co-authored-by: Nick Taylor <[email protected]>
open-sauced · Sep 16, 2024 · e8cf97a · e8cf97a
1 parent 45c33f3
commit e8cf97a
Show file tree

Hide file tree

Showing 2 changed files with 112 additions and 42 deletions.
diff --git a/.sauced.yaml b/.sauced.yaml
@@ -16,11 +16,8 @@ attribution:
     - [email protected]
   zeucapua:
     - [email protected]
-  bekahhw:
-    - [email protected]
-    - [email protected]
   BekahHW:
     - [email protected]
+    - [email protected]
   adiati98:
     - [email protected]
-
diff --git a/docs/tools/pizza-cli/codeowners.md b/docs/tools/pizza-cli/codeowners.md
@@ -20,65 +20,108 @@ Key benefits of using the codeowners command:
 
 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
+## Configuration Generation
 
-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.
+**New in v1.4.0, the `pizza generate config` command helps you create `.sauced.yaml` configuration files for your projects:**
+
+```sh
+pizza generate config /path/to/local/git/repo
+```
+
+**This command will:**
+- Iterate through the git ref-log
+- Inspect email signatures for commits
+- In interactive mode, ask you to attribute those users with GitHub handles
+
+The resulting `.sauced.yaml` file can be used to attribute owners in a `CODEOWNERS` file during `pizza generate codeowners`.
+
+### Configuration Generation 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
+
+### Configuration Generation 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
+   ```
+
+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
+   ```
+
+### Creating a `.sauced.yaml` File Manually
+
+If you prefer to create the `.sauced.yaml` file manually, you can do so by following these steps:
 
 <details>
-<summary>Selecting appropriate codeowners</summary>
+   <summary>Selecting appropriate codeowners</summary>
 
-When deciding who to include in your `.sauced.yaml` file, consider the following:
+   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.
+   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.
+   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.
+   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.
+   4. **Long-term contributors**: Consider long-standing contributors who have demonstrated commitment to the project.
 
-:::tip
+   :::tip
 
-Be cautious about including external contributors. Only include those who have been vetted and are trusted to review and approve changes.
+   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>
+   Codeowners will be automatically requested for review on pull requests that modify code they own.
 
-### Tips for identifying potential codeowners
+   <details>
+      <summary>Tips for identifying potential codeowners</summary>
 
-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.
+      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.
+      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.
+   </details>
 
-### Mapping GitHub usernames to email addresses
+   <details>
+      <summary>Mapping GitHub usernames to email addresses</summary>
 
-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:
+      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
-   ```
+         ```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.
+      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:
+      Alternatively, you can run the following command to get a list of your contributors' email addresses:
 
-   ```bash
-   git log --format='%ae' | sort -u
-   ```
+         ```bash
+         git log --format='%ae' | sort -u
+         ```
+   </details>
 
-## Creating the `.sauced.yaml` file
+</details>
 
-After identifying appropriate codeowners, create the `.sauced.yaml` file in your repository's root directory with the following structure:
+## Attribution Configuration
+
+After identifying appropriate codeowners, the `.sauced.yaml` file should use the following structure:
 
    ```yaml
    attribution:
@@ -91,7 +134,38 @@ After identifying appropriate codeowners, create the `.sauced.yaml` file in your
 
 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
+### Attribution Fallback
+
+There are cases where there may not be a codeowner derived from the range of commits being inspected. To handle this, you can include an `attribution-fallback` key in your config:
+
+```yaml
+attribution:
+  jpmcb:
+    - [email protected]
+  brandonroberts:
+    - [email protected]
+attribution-fallback:
+  - open-sauced/engineering
+```
+
+This field in the config can be used to attribute files that don't have an active attribution.
+
+Without fallback, the codeowners generation might create a CODEOWNERS file like this:
+
+```codeowners
+/file/with/codeowner @jpmcb
+/file/without/codeowner
+```
+
+**With the fallback configured, it would generate:**
+
+```codeowners
+/file/with/codeowner @jpmcb
+/file/without/codeowner @open-sauced/engineering
+```
+This ensures that all files have an assigned owner, even if there were no commits in the specified time range for certain files.
+
+## Codeowners Command
 
 To generate the CODEOWNERS file, you need to provide the path to your repository as an argument:
 
@@ -109,7 +183,6 @@ pizza generate codeowners .
 - 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.