NAME

Review::Helper::Feedback - Export a review's feedback and requests.

DESCRIPTION

Builds the feedback export: every feedback item and request in the review, from any iteration, oldest first. Each anchors to a target (review, commit, file, section, or line or flag for feedback), with commit, path and section ({ name, package }) set as far as the target reaches. A commit item in a squashed iteration split into topics names its topic; topic is null otherwise, or kept as context on an item that moved to the review when its topic went. A file item may also carry section: the section it was on before a re-split took that section away, kept as context. A feedback item's flag is { note, sentence, path, lines } for a flag target, or for feedback a retired flag left on its file or commit (its sentence stored with the feedback), and null otherwise. published is null until the feedback is posted to the pull or merge request under review. reviewer names who wrote the item, null when the file did not record it.

SYNOPSIS

use Review::Helper::Feedback;

my $export = Review::Helper::Feedback->new(db => $db)->export(open => 1);

ATTRIBUTES

$db = $feedback->db()

The Review::Helper::DB of the review. Required.

PUBLIC METHODS

$data = $feedback->export()
$data = $feedback->export(open => 1)

A hashref with format (review-feedback), format_version (1), review (its id), source (the pull or merge request URL, or undef), iteration, base and head (of the latest iteration), feedback and requests. With open, only items whose status is open.

$entry = $feedback->feedback_entry($row)
$entry = $feedback->request_entry($row)

One exported feedback item or request from its database row.

$flag = $feedback->flag_of($row)

The flag a feedback row is on, or was on before the agent retired it, as { note, sentence, path, lines }: its flag, flag_sentence and path, and the [start, end] of the flag with that note id in the row's iteration (null for a whole-file or whole-commit flag, or one no longer there); undef for feedback on no flag.

$data = $feedback->publish()
$data = $feedback->publish(@ids)

What to post to the pull or merge request: a hashref with format (review-publish), format_version (1), review, source, head (of the latest iteration) and items, one per feedback item that is open and not yet published, or per item of @ids, in that order, each once. Croaks on an id with no item. Each item is { id, text, anchor, fallback }, as publish_item builds it. The prefixes and the line-fit rule are those of the review file format's publish list (see Review::Helper::Manual).

$item = $feedback->publish_item($row)

One item to post. text is the general comment: the location prefix, a blank line, then body exactly as stored, or body alone for an item with no prefix. When a line comment fits, text is body alone, anchor is { path, line, side } and fallback the general comment to post if the forge refuses the line comment; otherwise both are undef.

($prefix, $anchor) = $feedback->location($row)

The item's location prefix (undef for whole-change feedback with no topic) and, for a line item or a flag item with lines, its anchor from line_anchor.

$anchor = $feedback->line_anchor($row, $line, $side)

{ path, line, side } for a line comment at $line on $side of the row's commit and path, or undef when it does not fit: when the latest iteration lacks the row's commit, or another of its commits changes the path after it (new side) or before it (old side), or at all when the iteration has merged-in commits. When the row's commit renamed the file, a change to its old path counts too. On the old side of a squashed iteration's item, it fits when that iteration's base is the latest one's.

$anchor = $feedback->anchor($row)
$anchor = Review::Helper::Feedback->anchor($row)

The target, commit, topic, path and section of a feedback or request row. It needs no object; Review::Helper::Sheet calls it on the class for its feedback and debate items.

SOURCE

The source code repository for Review-Helper can be found at https://github.com/exodist/Review-Helper.

MAINTAINERS

Chad Granum <exodist7@gmail.com>

AUTHORS

Chad Granum <exodist7@gmail.com>

COPYRIGHT

Copyright Chad Granum <exodist7@gmail.com>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See https://dev.perl.org/licenses/