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** |