You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* 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]>
Copy file name to clipboardExpand all lines: docs/tools/pizza-cli/codeowners.md
+111-38
Original file line number
Diff line number
Diff line change
@@ -20,65 +20,108 @@ Key benefits of using the codeowners command:
20
20
21
21
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.
22
22
23
-
## Creating a `.sauced.yaml` file
23
+
## Configuration Generation
24
24
25
-
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.
25
+
**New in v1.4.0, the `pizza generate config` command helps you create `.sauced.yaml` configuration files for your projects:**
26
+
27
+
```sh
28
+
pizza generate config /path/to/local/git/repo
29
+
```
30
+
31
+
**This command will:**
32
+
- Iterate through the git ref-log
33
+
- Inspect email signatures for commits
34
+
- In interactive mode, ask you to attribute those users with GitHub handles
35
+
36
+
The resulting `.sauced.yaml` file can be used to attribute owners in a `CODEOWNERS` file during `pizza generate codeowners`.
37
+
38
+
### Configuration Generation Flags
39
+
40
+
-`-i, --interactive`: Enter interactive mode to attribute each email manually
41
+
-`-o, --output-path string`: Set the directory for the output file
42
+
-`-h, --help`: Display help for the command
43
+
44
+
### Configuration Generation Examples
45
+
46
+
1. Generate a config file in the current directory:
47
+
```sh
48
+
pizza generate config ./
49
+
```
50
+
51
+
2. Generate a config file interactively:
52
+
```sh
53
+
pizza generate config ./ -i
54
+
```
55
+
56
+
3. Generate a config file from the current directory and place resulting `.sauced.yaml` in a specific output directory:
57
+
```sh
58
+
pizza generate config ./ -o /path/to/directory
59
+
```
60
+
61
+
### Creating a `.sauced.yaml` File Manually
62
+
63
+
If you prefer to create the `.sauced.yaml` file manually, you can do so by following these steps:
This lists active contributors in the last 6 months.
100
+
</details>
62
101
63
-
### Mapping GitHub usernames to email addresses
102
+
<details>
103
+
<summary>Mapping GitHub usernames to email addresses</summary>
64
104
65
-
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:
105
+
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:
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.
111
+
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.
72
112
73
-
Alternatively, you can run the following command to get a list of your contributors' email addresses:
113
+
Alternatively, you can run the following command to get a list of your contributors' email addresses:
74
114
75
-
```bash
76
-
git log --format='%ae'| sort -u
77
-
```
115
+
```bash
116
+
git log --format='%ae' | sort -u
117
+
```
118
+
</details>
78
119
79
-
## Creating the `.sauced.yaml` file
120
+
</details>
80
121
81
-
After identifying appropriate codeowners, create the `.sauced.yaml` file in your repository's root directory with the following structure:
122
+
## Attribution Configuration
123
+
124
+
After identifying appropriate codeowners, the `.sauced.yaml` file should use the following structure:
82
125
83
126
```yaml
84
127
attribution:
@@ -91,7 +134,38 @@ After identifying appropriate codeowners, create the `.sauced.yaml` file in your
91
134
92
135
Only include the GitHub usernames and email addresses of the individuals you've identified as appropriate codeowners based on the considerations mentioned above.
93
136
94
-
## Pizza CLI Codeowners Command
137
+
### Attribution Fallback
138
+
139
+
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:
This field in the config can be used to attribute files that don't have an active attribution.
152
+
153
+
Without fallback, the codeowners generation might create a CODEOWNERS file like this:
154
+
155
+
```codeowners
156
+
/file/with/codeowner @jpmcb
157
+
/file/without/codeowner
158
+
```
159
+
160
+
**With the fallback configured, it would generate:**
161
+
162
+
```codeowners
163
+
/file/with/codeowner @jpmcb
164
+
/file/without/codeowner @open-sauced/engineering
165
+
```
166
+
This ensures that all files have an assigned owner, even if there were no commits in the specified time range for certain files.
167
+
168
+
## Codeowners Command
95
169
96
170
To generate the CODEOWNERS file, you need to provide the path to your repository as an argument:
97
171
@@ -109,7 +183,6 @@ pizza generate codeowners .
109
183
- Ensure you have the necessary permissions to read the repository and write the CODEOWNERS file.
110
184
- The command requires a `.sauced.yaml` file in the repository root for accurate attribution (as described in the previous section).
111
185
- If you encounter any errors, double-check that you've provided the correct path to your repository.
112
-
-
113
186
:::
114
187
115
188
The codeowners command will analyze your repository's commit history and generate a CODEOWNERS file based on contributors' activity in the last 90 days.
0 commit comments