-
Notifications
You must be signed in to change notification settings - Fork 27
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: add prow plugins document (#466)
- Loading branch information
Showing
12 changed files
with
384 additions
and
31 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,35 @@ | ||
| # assign | ||
|
|
||
| ## Design Background | ||
|
|
||
| Collaborating on a large repository requires assigning PRs or issues to specific collaborators to follow up on, but without write access, you can't assign them directly through the GitHub page. | ||
|
|
||
| [assign](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/assign) provides a command that allows the bot to assign collaborators and request reviewers. | ||
|
|
||
| ## Design | ||
|
|
||
| The plugin was designed and developed by the Kubernetes community and provides two commands: | ||
|
|
||
| - `/[un]assign @someone hi-rustin`: assign or un-assign Issue/PR to someone and hi-rustin. | ||
| - `/[un]cc @someone hi-rustin`: request or un-request someone and hi-rustin to review PR. | ||
|
|
||
| Note: If you do not specify a GitHub account after the command, it defaults to yourself. | ||
|
|
||
| ## Parameter Configuration | ||
|
|
||
| No configuration | ||
|
|
||
| ## Reference documentations | ||
|
|
||
| - [command help](https://prow.tidb.io/plugins?repo=ti-community-infra%2Ftichi) | ||
| - [code](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/assign) | ||
|
|
||
| ## Q&A | ||
|
|
||
| ### Why do you support usernames that do not start with `@`? | ||
|
|
||
| > https://github.com/ti-community-infra/tichi/issues/426 | ||
| When starting with `@`, GitHub automatically sends an email to the corresponding user. Another notification email will send by the bot when the user has been assigned, or requested to review. | ||
| To reduce the number of unnecessary emails, `assign` allows usernames that do not start with `@`. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # milestone | ||
|
|
||
| ## Design Background | ||
|
|
||
| On large repositories we use milestones to track the progress of PRs and Issues, but GitHub restricts the ability to add milestones to Issues/PRs to collaborators with write access. | ||
|
|
||
| [milestone](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/milestone) provides a command that allows the bot to add the corresponding milestone. | ||
|
|
||
| ## Permissions Design | ||
|
|
||
| This plugin is primarily responsible for adding milestones, so only the milestone management team can use this command. | ||
|
|
||
| ## Design | ||
|
|
||
| The plugin was designed and developed by the Kubernetes community and provides two commands. | ||
|
|
||
| - `/milestone v1.3.2 v1.4` adds milestone v1.3.2 and v1.4. | ||
| - `/milestone clear` clears all milestones on Issue/PR. | ||
|
|
||
| Note: Only the milestone management team can use this command. | ||
|
|
||
| ## Parameter Configuration | ||
|
|
||
| | Parameter Name | Type | Description | | ||
| | ------------------------- | ------ | ---------------- | | ||
| | maintainers_id | int | GitHub Team ID | | ||
| | maintainers_team | string | GitHub team name | | ||
| | maintainers_friendly_name | string | Team nickname | | ||
|
|
||
| For example: | ||
|
|
||
| ```yaml | ||
| repo_milestone: | ||
| ti-community-infra/test-dev: | ||
| maintainers_id: 4300209 | ||
| maintainers_team: bots-maintainers | ||
| maintainers_friendly_name: Robots Maintainers | ||
| ``` | ||
| ## Reference documents | ||
| - [command help](https://prow.tidb.io/plugins?repo=ti-community-infra%2Ftichi) | ||
| - [code](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/milestone) | ||
| ## Q&A | ||
| ### How can I get my GitHub Team ID? | ||
| ```sh | ||
| curl -H "Authorization: token <token>" "https://api.github.com/orgs/<org-name>/teams?page=N" | ||
| ``` | ||
| The above API allows you to get the details of all GitHub teams under that organization. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| # needs-rebase | ||
|
|
||
| ## Design Background | ||
|
|
||
| GitHub doesn't usually alert PR authors to resolve PR conflicts, which can result in our PR not being automatically merged by the bot and requiring to alert them manually to resolve the conflict. Also, we can't see which one have conflicts in the PRs list. | ||
|
|
||
| [needs-rebase](https://github.com/kubernetes/test-infra/tree/master/prow/external-plugins/needs-rebase) can periodically check for conflicts in PR by adding the `needs-rebase` label and remind PR authors to resolve conflicts. | ||
|
|
||
| ## Design | ||
|
|
||
| This plugin was designed and developed by the Kubernetes community. They implemented it with the idea that not only should all PRs be scanned periodically to add or remove `needs-rebase` label, but also that those PRs that are active and have replies should have `needs-rebase` label added as soon as possible to remind them to resolve conflicts. | ||
|
|
||
| ## Parameter Configuration | ||
|
|
||
| No configuration | ||
|
|
||
| ## Reference documents | ||
|
|
||
| - [command help](https://prow.tidb.io/plugins?repo=ti-community-infra%2Ftichi) | ||
| - [code](https://github.com/kubernetes/test-infra/tree/master/prow/external-plugins/needs-rebase) | ||
|
|
||
| ## Q&A | ||
|
|
||
| ### Is it disturbing to PR authors that the bot comments while adding `needs-rebase` label? | ||
|
|
||
| > https://github.com/ti-community-infra/tichi/issues/408 | ||
| This is because GitHub doesn't alert you when a PR conflict has occurred, and GitHub doesn't notify you when a bot adds `needs-rebase`, so we have to explicitly notify you via a reply. | ||
| Also, **after you resolve the conflict the bot automatically removes the `needs-rebase` label and deletes the outdated and useless replies. ** | ||
|
|
||
| ### How often are scans performed? | ||
|
|
||
| The automatic scan is performed once every 24 hours. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| # size | ||
|
|
||
| ## Design Background | ||
|
|
||
| In the GitHub PR list, we don't directly know the size of the PR code changes (the number of lines added or removed). However, we sometimes schedule our reviews based on the size of the changes. | ||
|
|
||
| [size](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/size) adds a size label to the PR based on the number of lines added or deleted to the PR code. | ||
|
|
||
| ## Design | ||
|
|
||
| This plugin was designed and developed by the Kubernetes community, and it's implementation is very simple. size adds `size/*` labels to a PR by detecting the number of lines added or deleted by the PR, and each size label has a range of lines corresponding to. | ||
|
|
||
| - `size/XS`: 0-9 | ||
| - `size/S`: 10-29 | ||
| - `size/M`: 30-89 | ||
| - `size/L`: 89-269 | ||
| - `size/XL`: 270-519 | ||
| - `size/XXL`: 520+ | ||
|
|
||
| ## Parameter Configuration | ||
|
|
||
| | Parameter Name | Type | Description | | ||
| | -------------- | ---- | ----------------------------- | | ||
| | s | int | size/S number of rows | | ||
| | m | int | size/M number of rows | | ||
| | l | int | number of rows for size/L | | ||
| | xl | int | The number of rows in size/XL | | ||
| | xxl | int | size/XXL rows | | ||
|
|
||
| For example: | ||
|
|
||
| ```yaml | ||
| size: | ||
| s: 10 | ||
| m: 30 | ||
| l: 100 | ||
| xl: 500 | ||
| xxl: 1000 | ||
| ``` | ||
| ## Reference Documents | ||
| - [command help](https://prow.tidb.io/plugins?repo=ti-community-infra%2Ftichi) | ||
| - [code](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/size) | ||
| ## Q&A | ||
| ### Will it automatically add and remove `size/*` labels when I change my PR? | ||
|
|
||
| Yes, it will dynamically add and remove labels based on code changes. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| # assign | ||
|
|
||
| ## 设计背景 | ||
|
|
||
| 在大型仓库上协作需要将 PR 或 Issue 分配给特定的协作者来跟进，但是如果没有写权限，是无法直接通过 GitHub 页面去分配的。 | ||
|
|
||
| [assign](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/assign) 可以提供命令让机器人帮助我们分配协作者和请求 reviewer。 | ||
|
|
||
| ## 设计思路 | ||
|
|
||
| 该插件由 Kubernetes 社区设计开发，提供了两个命令： | ||
|
|
||
| - `/[un]assign @someone hi-rustin`: 将 Issue/PR 分配或取消分配给 someone 和 hi-rustin。 | ||
| - `/[un]cc @someone hi-rustin`: 请求或取消 someone 和 hi-rustin review PR。 | ||
|
|
||
| 注意：如果在命令后不指定 GitHub 账号，则默认是自己。 | ||
|
|
||
| ## 参数配置 | ||
|
|
||
| 无参数 | ||
|
|
||
| ## 参考文档 | ||
|
|
||
| - [assign doc](https://prow.tidb.io/plugins?repo=ti-community-infra%2Ftichi) | ||
| - [代码实现](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/assign) | ||
|
|
||
| ## Q&A | ||
|
|
||
| ### 为什么支持以非`@`开头的用户名？ | ||
|
|
||
| > https://github.com/ti-community-infra/tichi/issues/426 | ||
| 当以`@`开头时，GitHub 会自动发送邮件给对应用户，同时在机器人分配或者请求 review 后也会发送一个通知邮件。 | ||
| 为了减少不必要的邮件数量， assign 允许非`@`开头的用户名。 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # milestone | ||
|
|
||
| ## 设计背景 | ||
|
|
||
| 在大型仓库上我们会使用 milestone 来追踪 PR 和 Issue 的进度，但是 GitHub 限制只有写权限的协作者才能为 Issue/PR 添加 milestone。 | ||
|
|
||
| [milestone](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/milestone) 可以提供命令让机器人添加对应的 milestone。 | ||
|
|
||
| ## 权限设计 | ||
|
|
||
| 该插件主要负责添加 milestone，所以只能让 milestone 的管理团队来使用该命令。 | ||
|
|
||
| ## 设计思路 | ||
|
|
||
| 该插件由 Kubernetes 社区设计开发，提供了两个命令： | ||
|
|
||
| - `/milestone v1.3.2 v1.4` 添加 milestone v1.3.2 和 v1.4。 | ||
| - `/milestone clear` 清除 Issue/PR 上所有的 milestones。 | ||
|
|
||
| 注意：只有 milestone 管理团队才可以使用该命令。 | ||
|
|
||
| ## 参数配置 | ||
|
|
||
| | 参数名 | 类型 | 说明 | | ||
| | ------------------------- | ------ | -------------- | | ||
| | maintainers_id | int | GitHub 团队 ID | | ||
| | maintainers_team | string | GitHub 团队名 | | ||
| | maintainers_friendly_name | string | 团队昵称 | | ||
|
|
||
| 例如： | ||
|
|
||
| ```yaml | ||
| repo_milestone: | ||
| ti-community-infra/test-dev: | ||
| maintainers_id: 4300209 | ||
| maintainers_team: bots-maintainers | ||
| maintainers_friendly_name: Robots Maintainers | ||
| ``` | ||
| ## 参考文档 | ||
| - [milestone doc](https://prow.tidb.io/plugins?repo=ti-community-infra%2Ftichi) | ||
| - [代码实现](https://github.com/kubernetes/test-infra/tree/master/prow/plugins/milestone) | ||
| ## Q&A | ||
| ### 我如何才能获取我 GitHub 团队的 ID？ | ||
| ```sh | ||
| curl -H "Authorization: token <token>" "https://api.github.com/orgs/<org-name>/teams?page=N" | ||
| ``` | ||
| 通过以上 API 可以获取该组织下所有的 GitHub 团队详细信息。 |
Oops, something went wrong.