163 lines
7.1 KiB
Markdown
163 lines
7.1 KiB
Markdown
Workflow-PR bot
|
|
===============
|
|
|
|
Keeps ProjectGit PRs in-sync with the relative PackageGit PRs.
|
|
|
|
Target Usage
|
|
------------
|
|
|
|
Any project (devel, codestream, product, etc.) that accepts PRs.
|
|
|
|
|
|
Main Tasks
|
|
----------
|
|
|
|
* **Synchronization**:
|
|
* When a **PackageGit PR** is created for a package on a specific project branch, a corresponding PR is automatically generated in **ProjectGit**.
|
|
* When a PackageGit PR is updated, the corresponding PR against the ProjectGit is updated.
|
|
* A link to the PackageGit PR is stored in the body of the ProjectGit PR comments in the following format:
|
|
* `PR: organization/package_name!pull_request_number`
|
|
* Example: `PR: pool/curl!4`
|
|
* It closes an empty ProjectGit PR (e.g., if a PR was initially created for a single package but later integrated into a larger ProjectGit PR).
|
|
* It forwards the Work In Progress (WIP) flag to the ProjectGit PR. If the ProjectGit PR references multiple Package PRs, triggering the WIP flag on the ProjectGit PR side only requires a single WIP package PR.
|
|
|
|
* **Reviewer Management**:
|
|
* It adds required reviewers in the ProjectGit PR.
|
|
* It adds required reviewers in the PackageGit PR.
|
|
* If new commits are added to a PackageGit PR, reviewers who have already approved it will be re-added.
|
|
|
|
* **Merge Management**:
|
|
* Manages PR merges based on configuration flags (`ManualMergeOnly`, `ManualMergeProject`).
|
|
* In general, merge only happens if all mandatory reviews are completed.
|
|
* **ManualMergeProject** is stricter than **ManualMergeOnly** and has higher priority.
|
|
|
|
| Flag | Value | Behavior |
|
|
| ----- | ----- | ----- |
|
|
| ManualMergeProject | true | Both ProjectGit and PackageGit PRs are merged upon an allowed project maintainer commenting "merge ok” in the ProjectGit PR. |
|
|
| ManualMergeOnly | true | Both PackageGit PR and ProjectGit PR are merged upon an allowed package maintainer or project maintainer commenting “merge ok” in the PackageGit PR. |
|
|
| ManualMergeOnly and ManualMergeProject | false | Both ProjectGit and PackageGit PRs are merged as soon as all reviews are completed in both PrjGit and PkgGit PRs. |
|
|
|
|
Config file
|
|
-----------
|
|
|
|
* Filename: `workflow.config`
|
|
* Location: ProjectGit
|
|
* Format: non-standard JSON (comments allowed)
|
|
|
|
| Field name | Details | Mandatory | Type | Allowed Values | Default |
|
|
| ----- | ----- | ----- | ----- | ----- | ----- |
|
|
| *Workflows* | Type of workflow | yes | string | “pr” | |
|
|
| *Organization* | The organization where PackageGit PRs are expected to occur | yes | string | | |
|
|
| *Branch* | The designated branch for PackageGit PRs | yes | string | | |
|
|
| *GitProjectName* | Repository and branch where the ProjectGit lives. | no | string | **Format**: `org/project_repo#branch` | By default assumes `_ObsPrj` with default branch in the *Organization* |
|
|
| *ManualMergeOnly* | Merges are permitted only upon receiving a "merge ok" comment from designated maintainers in the PkgGit PR. | no | bool | true, false | false |
|
|
| *ManualMergeProject* | Merges are permitted only upon receiving a "merge ok" comment in the ProjectGit PR from project maintainers. | no | bool | true, false | false |
|
|
| *ReviewRequired* | (NOT IMPLEMENTED) If submitter is a maintainer, require review from another maintainer if available. | no | bool | true, false | false |
|
|
| *NoProjectGitPR* | Do not create PrjGit PR, but still perform other tasks. | no | bool | true, false | false |
|
|
| *Reviewers* | PrjGit reviewers. Additional review requests are triggered for associated PkgGit PRs. PrjGit PR is merged only when all reviews are complete. | no | array of strings | | `[]` |
|
|
| *ReviewGroups* | If a group is specified in Reviewers, its members are listed here. | no | array of objects | | `[]` |
|
|
| *ReviewGroups > Name* | Name of the group | no | string | | |
|
|
| *ReviewGroups > Reviewers* | Members of the group | no | array of strings | | |
|
|
| *ReviewGroups > Silent* | Add members for notifications. If true, members are not explicitly requested to review. If one member approves, others are removed. | no | bool | true, false | false |
|
|
|
|
|
|
Reviewers
|
|
---------
|
|
|
|
Reviews is a list of accounts that need to review package and/or project. They have specific syntax
|
|
|
|
[~][*|-|+]username
|
|
|
|
A tilde (`~`) before a prefix signifies an advisory reviewer. Their input is requested, but their review status will not otherwise affect the process.
|
|
|
|
Other prefixes indicate project or package association of the reviewer:
|
|
|
|
* `*` indicates project *and* package
|
|
* `-` indicates project-only reviewer
|
|
* `+` indicates package-only reviewer
|
|
|
|
`+` is implied.
|
|
|
|
For example: `[foo, -bar, ~*moo]` results in:
|
|
* foo: package reviews
|
|
* bar: project reviews
|
|
* moo: package and project reviews, but ignored
|
|
|
|
Package Deletion Requests
|
|
-------------------------
|
|
(NOT YET IMPLEMENTED)
|
|
|
|
* **Removing a Package:**
|
|
To remove a package from a project, submit a ProjectGit Pull Request (PR) that removes the corresponding submodule. The bot will then rename the project branch in the pool by appending "-removed" to its name.
|
|
|
|
* **Adding a Package Again:**
|
|
If you wish to re-add a package, create a new PrjGit PR which adds again the submodule on the branch that has the "-removed" suffix. The bot will automatically remove this suffix from the project branch in the pool.
|
|
|
|
|
|
Labels
|
|
------
|
|
|
|
The following labels are used, when defined in Repo/Org.
|
|
|
|
| Label Config Entry | Default label | Description
|
|
|--------------------|----------------|----------------------------------------
|
|
| StagingAuto | staging/Auto | Assigned to Project Git PRs when first staged
|
|
| ReviewPending | review/Pending | Assigned to Project Git PR when package reviews are still pending
|
|
| ReviewDone | review/Done | Assigned to Project Git PR when reviews are complete on all package PRs
|
|
|
|
|
|
Maintainership
|
|
--------------
|
|
|
|
Filename: \_maintainership.json
|
|
Location: ProjectGit
|
|
Format: JSON
|
|
Fields:
|
|
|
|
| Key | Value | Notes |
|
|
| ----- | ----- | ----- |
|
|
| package name | array of strings representing the package maintainers | List of package maintainers |
|
|
| “” (empty string) | array of strings representing the project maintainers | List of project maintainers |
|
|
|
|
Maintainership information is defined per project. For PackageGit PR reviews, package maintainers are combined with project maintainers. A review by any of these maintainers is acceptable.
|
|
|
|
If the submitter is a maintainer it will not get a review requested.
|
|
|
|
Example:
|
|
|
|
```
|
|
{
|
|
"package1": [ "reviewer", "reviewer2"],
|
|
"package2": [],
|
|
|
|
// "project" maintainer
|
|
"": ["reviewer3", "reviewer4"]
|
|
}
|
|
```
|
|
|
|
Permissions
|
|
-----------
|
|
|
|
Permissions are extra permissions assigned to groups or individuals. Groups must be defined in
|
|
the `workflow.config`.
|
|
|
|
```
|
|
Permissions: []{
|
|
Permission: "force-push" | "release-engineering"
|
|
Members: []string
|
|
}
|
|
```
|
|
|
|
* `force-push` -- allows to issue force-push to the bot to merge even without reviews
|
|
* `release-engineering` -- merge, split package PRs and merge additional commits
|
|
|
|
NOTE: Project Maintainers have these permissions automatically.
|
|
|
|
Server configuration
|
|
--------------------------
|
|
|
|
**Configuration file:**
|
|
|
|
| Field | Type | Notes |
|
|
| ----- | ----- | ----- |
|
|
| root | Array of string | Format **org/repo\#branch** | |