Rules and Instructions¶

Overview¶

Two settings take plain words instead of options:

	Where	What it decides
Review rules	`.cloudaeye.rules`	What the review holds your code to
Human review instructions	`Instructions:` in `.cloudaeye.config`	When a person must review a pull request, and how many

Review Rules¶

Format¶

Each rule is a heading, the rule in plain words, and optionally the paths it applies to:

# Review rules

## No request bodies in logs
Never log a request or response body; log its size and the route instead.
- Applies to: `src/api/`

## Money is never a float
Amounts are integers in the smallest currency unit, or Decimal. Never float.
- Applies to: `services/payments/`, `services/billing/`

A rule covers the directory of the .cloudaeye.rules it is in, and everything below it.
- Applies to: narrows it to paths relative to that directory, each in backticks.
A rule with no Applies to line covers the whole directory.

Your Organization's Rules¶

The rules saved in the console under Custom Review Rules that apply to this repository are synced into the top-level .cloudaeye.rules every time you run /cloudaeye:config. When none apply, no file is created.

A synced rule's heading is its id:

## r12
Every API endpoint checks the caller's permissions before it reads or writes data.
- Applies to: `src/api/`

The next sync replaces it, so change a synced rule in the console, not in the file.

Your Own Rules¶

A rule you write has a name for a heading instead of an id. Syncing never touches it. Add one by hand, or run /cloudaeye:config rules.

Which Rules Apply¶

Rules add up from the root down: a change under services/payments/ follows the rules in the top-level .cloudaeye.rules and in services/payments/.cloudaeye.rules.
Each changed file is reviewed against the rules that cover it.
/cloudaeye:inspect, /cloudaeye:security, /cloudaeye:review and ultrareview's review follow them. Pull request reviews by the CloudAEye GitHub App follow the rules saved in the console.

Human Review Instructions¶

Where They Go¶

Instructions: is the last setting under ## Ultrareview > ### Human review policy. It is one paragraph, up to 2,000 characters, carried on indented lines under the label:

### Human review policy
- Max human reviewers to assign: 2   <!-- 1 | 2 | 3. Default 1 -->
- Instructions: Changes under `services/payments/` always need two humans. Pull requests
  from the Platform team need one reviewer from outside the team. Any change to a database
  migration needs a human review, even when every check passes.

They apply to pull requests only.

What They Can Ask For¶

Instructions can only ask for more review, never less:

A human review of a change CloudAEye would otherwise approve.
More reviewers, up to Max human reviewers to assign, which is one by default: set it to 2 or 3 for an instruction that asks for more people. A change that is not approved gets one reviewer unless an instruction asks for more. An instruction asking for more than the maximum gets the maximum.
Who should review, such as someone from outside the author's team.

They cannot approve a change, raise a hard limit or turn a check off. Use the settings for those.

How CloudAEye Reads Them¶

CloudAEye reads the instructions against the pull request: its author, the author's teams, the files it changes and the results of every check. When an instruction applies, the report quotes it beside the verdict. When CloudAEye cannot tell whether an instruction applies, it follows it.

Teams come from the Teams section of the repository's OWNERS.md files, read from the branch the pull request merges into. See /cloudaeye:create-owners.

A directory's instructions add to the top-level file's: a change under services/payments/ follows both.

Writing Good Instructions¶

Name what can be checked on the pull request: paths, the author or their team, a kind of change, or a check's result. Changes under infra/ need a reviewer from the Platform team.
One requirement a sentence, so the report can quote the one that applied.
Say the number: two humans, not extra eyes.