Crate hygiene

Expand description

Issue hygiene of this repository: the form of a pull request, and of a commit on main. The module book checks the book, wrap checks the wrap of its pages, blank finds two blank lines in a row, versions finds the name of a version of riff, ci picks the checks that just ci runs, and terminal finds the crates of the terminal in the dependencies of a crate.

§Design

A change reaches main through a pull request, as one squash commit. GitHub makes the commit from the pull request: its title, then the number of the pull request, then its body. So the form of the body is the form of each commit on main:

Closes #77

Pause and resume the riff. A new riff starts paused.

Issue: #77
Milestone: Wave 3

The link line, Closes #N or Refs #N, links the pull request and the issue. The last pull request of an issue has Closes #N, so its merge closes the issue. Each other one has Refs #N.
The trailers Issue: and Milestone: end the body. They name the issue and the wave in the same form in each commit. The trailer Milestone: names a wave by its number: Wave 3, with no name (milestone_value). The check compares only the number, so a rename of a wave breaks no pull request (names_milestone, 01M518A04JWYJE5FA1VR309SAA).
The trailers stand in the last block of git trailers of the message (trailers). Other trailers may stand in the block, before or after them: Signed-off-by:, Generated-by:. At the squash, GitHub adds a Co-authored-by: line for each co-author of the commits, in a paragraph of its own. So hygiene pr checks the message that the squash will make (PullRequest::squash_message), not only the body.
The merge wraps each line of the body over 72 characters (merge_wrap). The tail of a trailer line goes to a line with no Key:, and that line ends the block of trailers. So hygiene pr fails a trailer line over the width (trailer-wrap) before the merge.

hygiene pr N reads pull request N and its issue with gh, and runs check_pr. hygiene commit [REV] reads the message of a commit with git, and runs check_commit. Each error names its rule:

Rule	Finds
`link`	A body with no link line, or with more than one.
`keyword`	Another closing keyword of GitHub before an issue number, for example `Fixes #12`. It closes an issue with no check.
`title`	A title of a pull request that ends with `(#N)`. GitHub adds the number of the pull request.
`issue-trailer`	No `Issue: #N` trailer, more than one, or one that names another issue than the link line.
`milestone-trailer`	No `Milestone:` trailer, more than one, or one that names another wave than the pull request.
`trailer-wrap`	A line of the last block of trailers over 72 characters. The merge wraps it, and the wrapped part is no trailer line (`merge_wrap`).
`milestone`	A pull request or an issue with no milestone, or two different milestones.
`issue-open`	An issue that is closed.
`commit-title`	A commit title that does not end with `(#PR)`, or that names the issue in place of the pull request.

use hygiene::{Issue, PullRequest};

let pr = PullRequest::new(
    "Pause and resume the riff",
    "Closes #77\n\nPause the riff.\n\nIssue: #77\nMilestone: Wave 3\n",
    Some("Wave 3"),
);
let issue = Issue::new(77, "OPEN", Some("Wave 3"));
assert!(hygiene::check_pr(&pr, Some(&issue)).is_empty());

let commit = "Pause and resume the riff (#90)\n\nCloses #77\n\nIssue: #77\nMilestone: Wave 3\n";
assert!(hygiene::check_commit(commit).is_empty());

Modules§

blank: The blank check: hygiene blank PATH... fails when a Markdown file has two blank lines in a row.
book: The book check: hygiene book [DIR] builds the book and fails when it has a missing include or anchor, or when the build changes a tracked file.
ci: The checks that just ci runs for a diff.
part: The parts of the tests of the Gate.
terminal: Finds the crates of the terminal in the dependencies of a crate (01M54216PBE319RASGNMY9F0MR). riff-client holds no terminal code: the test riff_client_has_no_terminal_crate runs found on its Cargo.toml and on the Cargo.lock of the workspace.
versions: The versions check: hygiene versions [ROOT] fails when a text names a version of riff.
wrap: The wrap check: hygiene wrap [DIR] fails when a prose line of a Markdown file in DIR is longer than 72 characters.

Structs§

Error: A broken rule of issue hygiene.
Issue: An issue, as gh issue view --json number,state,milestone gives it.
Milestone: A milestone, as gh --json milestone gives it.
Person: A person, as gh gives an author. gh leaves out the fields that it does not know.
PullCommit: A commit of a pull request: the people that GitHub counts as its authors. They are the author, and each person of a Co-authored-by: line.
PullRequest: A pull request, as gh pr view --json title,body,milestone,author,commits gives it.

Enums§

Link: The link line of a pull request.
Rules: The rules that a check of a pull request applies.

Constants§

MERGE_WIDTH: The width of a line in the message of a squash commit: the merge wraps a longer line (merge_wrap).

Functions§

check_commit: Checks the message of a commit on main. Returns each broken rule.
check_pr: Checks a pull request and its issue. issue is None when the pull request names no issue. Returns each broken rule, in the order of the table of rules.
check_pr_for: Checks a pull request and its issue with the rules rules (check_pr with Rules::All).
issue_number: The issue of a pull request: the issue of its first link line, or of its Issue: trailer. hygiene pr reads this issue.
issue_ref: The number of #N.
merge_wrap: The text as the squash merge of GitHub leaves it: a line of MERGE_WIDTH characters or fewer stays as it is. A longer line loses its indent and its double spaces, and is filled again with whole words up to MERGE_WIDTH characters. The wrapped lines have no indent, and the next line does not join them. A word longer than the width stays on a line of its own.
milestone_value: The value of the trailer Milestone: for the milestone title: the wave by its number, Wave N with no name, or the whole title of a milestone that is not a wave (01M518A07QF1YACBYT91M0DD1R).
names_milestone: True when the trailer Milestone: value names the milestone title. Two waves match by their number, so the name of a wave can change. Each other milestone matches by its whole title (01M518A04JWYJE5FA1VR309SAA).
stray_keywords: Each closing keyword of GitHub before an issue number, outside the link lines. GitHub closes such an issue at the merge.
trailers: The trailers of a message: the lines Key: value of its last block of trailers. The block is the last paragraphs of the message that hold only such lines. GitHub adds its Co-authored-by: lines after a blank line, so the block may have more than one paragraph. A paragraph with a line of another form ends the block, and a last paragraph of that form leaves no trailer at all.
wave_number: The number N of the wave title title: Wave N, or Wave N: NAME with a name that is not blank. None for each other title.

Crate hygiene

Crate hygiene Copy item path

§Design

Modules§

Structs§

Enums§

Constants§

Functions§

Crate hygiene