Workflow-PR bot
===============

Keeps ProjectGit PR in-sync with a PackageGit PR


Areas of Responsibility
-----------------------

* Detects a PackageGit PR creation against a package and creates a coresponsing PR against the ProjectGit
* When a PackageGit PR is updated, the corresponding PR against the ProjectGit is updated
* Stores reference to the PackageGit PR in the headers of the ProjectGit PR comments, for later reference
   * this allows ProjectGit PR to be merged to seperated later (via another tool, for example)
* Initiates all staging workflows via review requests


Target Usage
------------

Any project (devel, etc) that accepts PR


Config file
-----------
JSON
* _Workflows_: ["pr"] -- pr entry enables pr workflow. **Mandatory**
* _Organization_: organization that holds all the packages **Mandatory**
* _Branch_: branch updated in repo's **Mandatory**
* _GitProjectName_: package in above org, or `org/package#branch` for PrjGit. By default assumes `_ObsPrj` with default branch and in the `Organization`
* _Reviewers_: accounts associated with mandatory reviews for PrjGit. Can trigger additional
               review requests for PrjGit or associated PkgGit repos. Only when all reviews are
               satisfied, will the PrjGit PR be merged. See Reviewers below.
* _ManualMergeOnly_: (true, false) only merge if "merge ok" comment/review by package or project maintainers or reviewers
* _ManualMergeProject_: (true, false) only merge if "merge ok" by project maintainers or reviewers
* _ReviewRequired_: (true, false) ignores that submitter is a maintainer and require a review from other maintainer IFF available
* _NoProjectGitPR_: (true, false) do not create PrjGit PRs, but still process reviews, etc.
* _Permissions_: permissions and associated accounts/groups. See below.
* _Labels_: (string, string) Labels for PRs. See below.

NOTE: `-rm`, `-removed`, `-deleted` are all removed suffixes used to indicate current branch is a placeholder for previously existing package. These branches will be ignored by the bot,  and if default, the package will be removed and will not be added to the project.
example:

    [
     {
        "Workflows": ["pr", "direct"],
        "Organization": "autogits",
        "GitProjectName": "HiddenPrj",
        "Branch": "hidden",
        "Reviewers": []
     },
     ...
    ]

Reviewers
---------

Reviews is a list of accounts that need to review package and/or project. They have specific syntax

    [~][*|-|+]username

General prefix of ~ indicates advisory reviewer. They will be requested, but ignored otherwise.

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


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 PR when reviews are still pending
| ReviewDone         | review/Done    | Assigned to PR when reviews are complete on this particular PR


Maintainership
--------------

Maintainership information is defined per project. For reviews, package maintainers are coalesced
with project maintainers. A review by any of the maintainers is acceptable.

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.