rules

Documentation

Overview

Package rules specifies a simple set of rules for checking GitHub PRs or Gerrit CLs for certain common mistakes, like no package in the first line of the commit message or having long lines in the commit message body.

A rule is primarily defined via a function that takes a Change (CL or PR) as input and reports zero or 1 findings, which is just a string (usually 1-2 short sentences). A rule can also optionally return a note, which might be auxiliary advice such as how to edit the commit message.

The FormatResults function renders the results into markdown. Each finding is shown to the user, currently in a numbered list of findings. The auxiliary notes are deduplicated, so that for example a set of rules looking for problems in a commit message can all return the same editing advice but that advice is then only shown to the user only once.

For example, for a commit message with a first line of:

fmt: Improve foo and bar.

That would currently trigger two rules, with an example formatted result of the following (including the deduplicated advice at the end):

Possible problems detected:
  1. The first word in the commit title after the package should be a
     lowercase English word (usually a verb).
  2. The commit title should not end with a period.

 To edit the commit message, see instructions [here](...). For guidance on commit
 messages for the Go project, see [here](...).

Rules currently err on the side of simplicity and avoiding false positives. It is intended to be straightforward to add a new rule.

Rules can be arranged to trigger completely independently of one another, or alternatively a set of rules can optionally be arranged in groups that form a precedence based on order within the group, where at most one rule from that group will trigger. This can be helpful in cases like:

• You'd like to have a "catch all" rule that should only trigger if another rule in the same group hasn't triggered.
• You have a rule that spots a more general problem and rules that spot more specific or pickier variant of the same problem and want to have the general problem reported if applicable without also reporting pickier findings that would seem redundant.
• A subset of rules that are otherwise intended to be mutually exclusive.

Index

• func FormatResults(results []Result) string
• type Change
  • func ParseCommitMessage(repo string, text string) (Change, error)
• type Result
  • func Check(change Change) (results []Result)

Functions

func FormatResults

func FormatResults(results []Result) string

FormatResults returns a string ready to be placed in a CL comment, formatted as simple markdown.

Types

type Change

type Change struct {
	// Repo is the repository as reported by Gerrit (e.g., "go", "tools", "vscode-go", "website").
	Repo string
	// Title is the commit message first line.
	Title string
	// Body is the commit message body (skipping the title on the first line and the blank second line,
	// and without the footers).
	Body string
}

Change represents a Gerrit CL and/or GitHub PR that we want to check rules against.

func ParseCommitMessage

func ParseCommitMessage(repo string, text string) (Change, error)

type Result

type Result struct {
	Name    string
	Finding string
	Note    string
}

Result contains the result of a single rule check against a Change.

func Check

func Check(change Change) (results []Result)

Check runs the defined rules against one Change.