From 8f3e30cd9ea1bd957a5c436460b6cb36e808080e Mon Sep 17 00:00:00 2001 From: BekahHW Date: Fri, 13 Sep 2024 15:45:20 -0400 Subject: [PATCH 1/4] Restructure codeowners to reduce noise --- .sauced.yaml | 7 +- docs/tools/pizza-cli/codeowners.md | 204 +++++++++++++++++++++++------ 2 files changed, 169 insertions(+), 42 deletions(-) diff --git a/.sauced.yaml b/.sauced.yaml index 259baf85..502ec4f5 100644 --- a/.sauced.yaml +++ b/.sauced.yaml @@ -16,11 +16,8 @@ attribution: - bdougie@users.noreply.github.com zeucapua: - coding@zeu.dev - bekahhw: - - BekahHW@users.noreply.github.com - - rhawrot@gmail.com BekahHW: - BekahHW@users.noreply.github.com + - rhawrot@gmail.com adiati98: - - adiati98@users.noreply.github.com - + - adiati98@users.noreply.github.com \ No newline at end of file diff --git a/docs/tools/pizza-cli/codeowners.md b/docs/tools/pizza-cli/codeowners.md index 8d7e5dbb..280b21f3 100644 --- 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:
-Selecting appropriate codeowners + Selecting appropriate codeowners -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. -
+ Codeowners will be automatically requested for review on pull requests that modify code they own. -### Tips for identifying potential codeowners +
+ 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. + 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. +
-### Mapping GitHub usernames to email addresses +
+ 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: + 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 + ``` +
-## Creating the `.sauced.yaml` file + -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: @@ -114,4 +157,91 @@ pizza generate codeowners . 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). \ No newline at end of file +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). + + + + + +--- +id: codeowners +title: "Pizza CLI Codeowners Command" +sidebar_label: "Codeowners" +keywords: +- "codeowners" +- "codeowners automation" +- "CLI codeowners" +--- + + + +## Codeowners Generation + +**To generate a CODEOWNERS file, use the `codeowners` command:** + +```sh +pizza generate codeowners /path/to/local/git/repo +``` + +**This command will:** +- **Iterate through the git ref-log** +- **Determine code owners based on the number of lines changed for each file within the given time range** +- **Set the first owner as the entity with the most lines changed** +- **Use a `.sauced.yaml` configuration file to attribute emails in commits with the given entities (like GitHub usernames or teams)** + +:::info +- Ensure you have the [Pizza CLI installed](pizza-cli.md) before running the command. +- The command requires a `.sauced.yaml` file in the repository root or in your home directory (`~/.sauced.yaml`) for accurate attribution. +- If you encounter any errors, double-check that you've provided the correct path to your repository. +::: + + + +### 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. + +2. 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 + +To find email addresses for contributors: + +```bash +git log --author="GitHub_Username" --format='%ae' | sort -u +``` + +Replace `GitHub_Username` with the actual GitHub username. + +Alternatively, to get a list of all contributors' email addresses: + +```bash +git log --format='%ae' | sort -u +``` + +### Creating the `.sauced.yaml` File + +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. + +## Automating Codeowners Updates + +To keep your CODEOWNERS file up-to-date automatically, you can use the `pizza-action`. To learn more about this GitHub action, see the [pizza-action docs](pizza-action.md) or visit [the repository](https://github.com/open-sauced/pizza-action). \ No newline at end of file From a5022b6e23f41ca7d40bf94dbb46ac1b777cfbfc Mon Sep 17 00:00:00 2001 From: BekahHW Date: Fri, 13 Sep 2024 15:53:35 -0400 Subject: [PATCH 2/4] Add fallback attribution --- docs/tools/pizza-cli/codeowners.md | 124 ++++++++--------------------- 1 file changed, 34 insertions(+), 90 deletions(-) diff --git a/docs/tools/pizza-cli/codeowners.md b/docs/tools/pizza-cli/codeowners.md index 280b21f3..8abc1fe6 100644 --- a/docs/tools/pizza-cli/codeowners.md +++ b/docs/tools/pizza-cli/codeowners.md @@ -58,7 +58,7 @@ The resulting `.sauced.yaml` file can be used to attribute owners in a `CODEOWNE pizza generate config ./ -o /path/to/directory ``` -## Creating a `.sauced.yaml` File Manually +### Creating a `.sauced.yaml` File Manually If you prefer to create the `.sauced.yaml` file manually, you can do so by following these steps: @@ -134,7 +134,38 @@ After identifying appropriate codeowners, the `.sauced.yaml` file should use the 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: + - john@opensauced.pizza + brandonroberts: + - brandon@opensauced.pizza +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: @@ -157,91 +188,4 @@ pizza generate codeowners . 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). - - - - - ---- -id: codeowners -title: "Pizza CLI Codeowners Command" -sidebar_label: "Codeowners" -keywords: -- "codeowners" -- "codeowners automation" -- "CLI codeowners" ---- - - - -## Codeowners Generation - -**To generate a CODEOWNERS file, use the `codeowners` command:** - -```sh -pizza generate codeowners /path/to/local/git/repo -``` - -**This command will:** -- **Iterate through the git ref-log** -- **Determine code owners based on the number of lines changed for each file within the given time range** -- **Set the first owner as the entity with the most lines changed** -- **Use a `.sauced.yaml` configuration file to attribute emails in commits with the given entities (like GitHub usernames or teams)** - -:::info -- Ensure you have the [Pizza CLI installed](pizza-cli.md) before running the command. -- The command requires a `.sauced.yaml` file in the repository root or in your home directory (`~/.sauced.yaml`) for accurate attribution. -- If you encounter any errors, double-check that you've provided the correct path to your repository. -::: - - - -### 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. - -2. 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 - -To find email addresses for contributors: - -```bash -git log --author="GitHub_Username" --format='%ae' | sort -u -``` - -Replace `GitHub_Username` with the actual GitHub username. - -Alternatively, to get a list of all contributors' email addresses: - -```bash -git log --format='%ae' | sort -u -``` - -### Creating the `.sauced.yaml` File - -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. - -## Automating Codeowners Updates - -To keep your CODEOWNERS file up-to-date automatically, you can use the `pizza-action`. To learn more about this GitHub action, see the [pizza-action docs](pizza-action.md) or visit [the repository](https://github.com/open-sauced/pizza-action). \ No newline at end of file +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). \ No newline at end of file From fa2dbd58e2063cc03bfaee4de7ccb45d1c747de6 Mon Sep 17 00:00:00 2001 From: BekahHW Date: Fri, 13 Sep 2024 15:56:04 -0400 Subject: [PATCH 3/4] Remove extra bullet --- docs/tools/pizza-cli/codeowners.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/tools/pizza-cli/codeowners.md b/docs/tools/pizza-cli/codeowners.md index 8abc1fe6..12babe5f 100644 --- a/docs/tools/pizza-cli/codeowners.md +++ b/docs/tools/pizza-cli/codeowners.md @@ -183,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. From 46ab1920b0abf1d8550f08768a9c1cd65f6471d6 Mon Sep 17 00:00:00 2001 From: BekahHW <34313413+BekahHW@users.noreply.github.com> Date: Mon, 16 Sep 2024 09:13:41 -0400 Subject: [PATCH 4/4] Add EOL char back in Co-authored-by: Nick Taylor --- .sauced.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.sauced.yaml b/.sauced.yaml index 502ec4f5..6de57b7d 100644 --- a/.sauced.yaml +++ b/.sauced.yaml @@ -20,4 +20,4 @@ attribution: - BekahHW@users.noreply.github.com - rhawrot@gmail.com adiati98: - - adiati98@users.noreply.github.com \ No newline at end of file + - adiati98@users.noreply.github.com