Add a reviewed summary to a pull request description

Use a marker in the GitHub description to choose where Proofline may write. After checking the review, request the summary from the console.

Write the description section#

Proofline can write a review's summary into a marked section of the pull request description on GitHub. The section holds a headline and summary of the change, the environments the review finished checking, and links to the Proofline check and the review. It lists no findings. Proofline writes it only when someone asks from the review page; a push or a new review does not update it.

The setting is off until an administrator turns it on. In Settings → Review policy → Code review, select Allow description section requests under Pull request description and save. To change one repository, open its Settings → Code review page and choose Allow requests in this repository or Off for this repository under Description section, then select Save review settings. Same as the organization follows the organization setting.

To ask for the section:

  1. On GitHub, edit the pull request description and add a line that reads only @prooflinedev description where the section belongs.
  2. In Proofline, open the Details tab of the completed review of the pull request's latest commit.
  3. Under Pull request description, select Write description section.

Adding the line does not start a write. The request needs you to be signed in to Proofline with GitHub write access to the repository, and Proofline checks that access again just before it writes. Pull request description does not appear on a review while the setting is off for its repository, unless the review already has a request.

Proofline replaces the line with the section, between the comment lines <!-- proofline:description:start --> and <!-- proofline:description:end -->, and leaves the rest of the description as it is. Keep both comment lines: a later request replaces what is between them, so you can ask again from a newer review without adding the line again.

The review page shows Writing description section until the request ends with one of these outcomes. Except after a successful write, a line under the outcome gives the cause.

OutcomeWhat happenedWhat to do
Description section writtenGitHub accepted the section.Nothing.
Description section already currentThe section already says what this review would write, so Proofline changed nothing.Nothing.
No description section to fillThe description has no @prooflinedev description line and no section.Add the line, then ask again.
Description section was removedProofline wrote a section on this pull request earlier, and its two comment lines are no longer both there, once each and in order.Delete any comment line that is left, add the @prooflinedev description line, then ask again.
Pull request head movedA commit was pushed after the request, or the pull request was closed without merging. Nothing was written.Wait for the review of the new commit and ask from that review.
Description kept changingThe description was edited three times while Proofline prepared the write. Nothing was written.Finish editing the description, then ask again.
Description write refusedProofline or GitHub did not allow the write, and the cause says why: for example the setting was turned off after the request, you no longer have write access, shadow mode is on, or the description would exceed GitHub's length limit.Resolve the cause, then ask again.
Description write outcome unknownGitHub did not confirm the edit. Proofline does not send it a second time.Check the description on GitHub. If the section is missing or out of date, ask again.

If Proofline does not accept the request, a message above the button says why, such as that this is not the completed review of the pull request's latest commit. If the request could not be sent, select Retry same request.

Search help

Tab to a result. Enter to open. Escape to close.