Providing Feedback for Policy Updates

Merge Requests are essential for tracking changes, updates, and new files in policy documentation. The approval process ensures accuracy, compliance, and alignment with agency policies before changes are merged.

This guide outlines the steps to review and provide feedback to the Policy Writers on the new changes. These updates can be questions about content, correcting text/grammar/spelling, ensuring the policy is accurate, or ensuring proper legal citations are provided.

As par of the Review and Approval process the approvers should provide the appropriate feedback to correct any identified issues or concerns.

The updates for this section are currently in progress.

Approval Training Guides

Providing Feedback

There are several different types of feedback that can be provided within GitLab and at various levels of specificity. The below outlines the 3 areas feedback can be provided.

  • Providing In-Line Feedback: Inline comments are ideal for pointing out issues, suggestions, or questions directly on a changed line.

  • Providing File Level Feedback: Entire document comments address issues that span a whole file.These are often added as general comments in the file’s changes and are not tied to a specific line.

  • Providing General Feedback: You can use the Comment section on the general table to provide ask questions on across all the changes, provide feedback, or ask for a follow-up.

Providing In-Line Feedback

  1. On the Merge Request select the Changes Tab:

    1. In the MR page, click on the "Changes" tab to view the file changes.

    2. Select a file from the list of changed files on the left sidebar or scroll to a file.

  2. Hover over a line number → a blue speech bubble appears → click it.

    1. (Optional) Drag to select multiple lines for a single comment thread.

  3. A comment section will be opened for the line. You can use the comment box to type in the desired feedback for that specific line.

    train comment feedback 3

  4. Once your feedback has been entered you click on the "Start Review" button to start a review.

    1. The button will display "Add to Review" if not the first comment.

    train comment feedback 4

  5. Repeat as needed for additional comments.

  6. Once ready to review please Start a Review

Providing File Level Feedback

  1. On the Merge Request select the Changes Tab:

    1. In the MR page, click on the "Changes" tab to view the file changes.

    2. Select a file from the list of changed files on the left sidebar or scroll to a file.

  2. You can click on the Comment Icon at the top of the File to open a Comment section.

    train comment feedback 1

  3. A comment section will be opened at the top of the Policy File. You can use the comment box to type in the desired feedback for the entire file.

    train comment feedback 2

  4. Once your feedback has been entered you click on the "Start Review" button to start a review.

    1. The button will display "Add to Review" if not the first comment.

  5. Repeat as needed for additional files or in-line comments.

  6. Once ready to review please Start a Review

Start a Review

  1. Once your feedback has been entered you click on the "Start Review" button to start a formal review.

  2. You can review all the comments you have entered on the GitLab Change section. Once all your comments have been completed click on the "Your Review Button" at the top of the page.

    train comment feedback 5

  3. This will popup a Submit your Review field.

    train comment feedback 6

    1. On this field you will find a summary of all the pending comments have made.

    2. You can add additional summary comment in the "Add optional summary content section" by clicking on that field.

    3. Select the "Request Changes" from the menu to prevent the Merge Request from proceeding until the changes have been made.

    4. Then Click the "Submit Review" button

  4. This wil submit the review. It will also create threads in the main Activity section of the Merge Request for each item you requested feedback on the general tab.

    train comment feedback 7

  5. Within each thread you and the policy writer(s) can have a discussion, if needed, on the changes.

  6. Once All the changes have been completed for a section you should click on the resolve thread button to close the request.

Providing General Feedback

  1. Go to the Overview tab (default landing page of the MR).

  2. Scroll to the bottom → Leave a comment box.

    1. (Optionally): You can reverse the Activity Sections from Descending to Ascending.

  3. For a standalone comment → type and click Comment now.

    train comment feedback 8

  4. For a formal review with approval status:

    1. Click Start a review. You can then add additional In-Line or File level comments to the review. Once ready to submit the review please Start a Review.