How-to page on reviewing a request

docs/airlock-includes/glossary.md

@@ -8,3 +8,5 @@
 *[consolidation]: Phase after independent review, when output checkers can discuss and consolidate feedback
 *[context]: Contextual description of the output files within a file group
 *[controls]: Statistical disclosure control measures that have been applied to the files within a file group
+*[vote]: An individual output checker's review of a file (i.e. approve/request changed)
+*[decision]: The combined decision on the file, based on the submitted reviews from output checkers (approved, request changes, conflicted.)

docs/explanation/workflow-and-permissions.md

@@ -20,3 +20,12 @@ or Returned states.
 This means that if a request is in the Submitted or Reviewed states, the output
 checking team must return the request to the author in order for files to be updated.
 Updating a file will reset any reviews associated with that file.
+
+## Retrictions for authors
+Airlock does not permit users to approve or request changes to files that are part of release requests they created themselves.
+
+## Downloading restrictions
+Please note that only request files (not workspace files) can be downloaded.
+Downloading is permitted **only** for the purposes of output checking.
+Request authors are not permitted to download files from their own requests,
+even if they are also output checkers.

docs/how-tos/index.md

@@ -19,6 +19,4 @@ For researchers:
 For output checkers:
 
 * [Review a request](review-a-request.md)
-* [Download a file](download-file.md)
-* [Reject a request](reject-request.md)
 * [Release files](release-files.md)

docs/how-tos/review-a-request.md

@@ -1,45 +1,176 @@
+Two output checkers perform must perform an independent review of
+each requested file.
+
+## View release requests that require action
+
+Use the navigation bar link to view all requests.
+
+![Requests index](../screenshots/requests_index.png)
+
+This page shows you any release requests that you have authored, and any
+release requests that are currently active.
+
 !!! note
-    This page is out of date
+    If you are not an output checker you will only see requests that you
+    have authored on this page.
+
+
+### Outstanding requests awaiting review
+These are requests that have been submitted and are awaiting or under review.
+Each request also shows your progress in reviewing the files.
+
+### Requests returned for changes/questions
+These requests are currently awaiting updates from the researcher, and do
+not require any action from you as an output checker.
+
+Release requests are labelled by workspace name and author. Click on one to
+view it.
+
+## View files requested for release
+
+The overview page for a release request displays the status of the
+request, and some summary details about the files requested for release.
+
+It also shows a log of recent activity.
+
+This page also contains buttons for various actions that can be performed
+on the request as a whole (submitting your review, returning the request to
+the researcher etc.).  In the example below, all buttons are disabled, as
+this request has not yet been reviewed.
+
+![Request overview](../screenshots/request_overview.png)
+
+The files in a release request can be browsed in the file browser tree. The
+highlighted colour and icons illustrate the review state of the files.
+This request has 3 output files, none of which have been reviewed yet, and
+one supporting file, all in a file group called "my-group".
+
+![Request file tree](../screenshots/request_tree.png)
+
+## View context and controls for a file group
+
+Click on the file group in the tree to view the file group information.
+
+![File group](../screenshots/file_group.png)
+
+File group information contains the information about the context and controls
+that the researcher has provided for these files. 
+
+## Review files
+
+### View a file content
+To review an individual file, click on the file in the tree to display its
+content in the browser.
+
+![Request file page](../screenshots/file_review.png)
+
+The `More` dropdown also allows you to [view the file in alternative ways](../reference/view-files-alt.md), or to [view the source code](../reference/view-source-code.md) underlying
+the file. You can also [download](../reference/downloading-files.md) if required.
+
+![More dropdown](../screenshots/more_dropdown_el_request_file.png)
+
+### View context, controls and comments
+The context, controls and comments related to this file's file group can be
+viewed from the file page by clicking on the Context button.
+
+![Context, controls and comments modal](../screenshots/context_modal.png)
 
-Two output checkers independently review each file and record their decisions using the buttons within Airlock.
-Whilst viewing a file in an Airlock release request, they have the option of: 
+### Vote on a file
+
+Use the buttons at the top of the file content to submit your vote
+for this file. Options are:
 
 * **Approve** — output meets disclosure requirements and is safe to be released
 * **Request Changes** — output is not currently acceptable for release. 
 
-!!!warning "Retrictions for authors"
-    Airlock does not permit users to approve or request changes to files that are part of release requests they created themselves.
+After approving or requesting changes to a file, the
+page will display your vote, as well as the overall decision for the
+file. You can change or reset your vote in the same way.
+
+![Request file post-approval](../screenshots/file_approved.png)
+
+You will see the colours and icons change in the file tree to indicate the
+files that you have voted on.
+
+![Request file post-approval](../screenshots/request_tree_post_voting.png)
+
+
+### Add comments
+
+Comments can be added to each file group, to ask questions, or
+provide information on why changes have been requested to any files.
+
+To add a comment, navigate to the file group by clicking on it in
+the file browser. Enter your comment text and click Save.
+
+![Comment form](../screenshots/reviewed_request_comment_in_progress.png)
+
+You can choose to make a comment public and visible to everyone, or 
+private, visible only to other output checkers. In either case, comments are
+hidden from the researcher until the request is returned (or approved/released). 
+
+![Comments on submitted request](../screenshots/reviewed_request_comments.png)
+
+Comments that are created as private can be updated to public at a later stage.
+This can be useful during the consolidation stage, if output checkers agree that
+the comment contains a question to the researcher that they would like to ask
+without revision. 
+
+### Submit your independent review
+
+After you have reviewed all files, you must submit your review. Navigate to
+the request overview page, and click the Submit review button, which will now
+be enabled.
+
+![Submit independent review](../screenshots/submit_review.png)
+
+After your review has been submitted, the request status will change.
+
+![After independent review submitted](../screenshots/submitted_review.png)
+
+
+### Consolidation
+
+Once two independent reviews have been submitted, the request moves into
+"Reviewed" status. At this stage, output checkers are able to see the
+combined decision on files, and comments that they have each made, and
+can discuss and decide how to proceed with the request.
+
+At this stage, more comments can be added or the visibility of existing
+comments can be changed. Output checkers should determine the set of
+comments that they intend to return to the researcher (if any).
+
+## Progress the request to the next stage
+
+To progress the request, navigate to the request overview
+page. Depending on the status of the file decisions, you will have the options to:
+
+### Return request to researcher
+
+If there are questions or changes have been requested, you will need to
+return the request to the researcher. Click the Return request button from the 
+request overview page.
+
+### Reject request
 
+On rare occasions, there may be a request that contains data that must not
+be released. In this case, you can reject the entire request.
 
-## Viewing release requests on Airlock
+!!! warning
+    Rejecting a request cannot be undone.
 
-1. After logging into Airlock, output checkers navigate to the Requests list to
-   view all open requests awaiting review. Note that if an output checker is the
-   author of a request, they will not see it in the outstanding requests list. 
-1. Output checkers identify the request by workspace name and requester username. A user
-   can have at most one active request per workspace. 
-1. Output checkers can view the files included in the request via the file
-    browser within Airlock. If required (e.g. in order to perform calculations
-    in a spreadsheet), output checkers can also downloaded files from Airlock.
+### Release files
 
-!!! warning "Downloading restrictions" 
-    Please note that only request files (not workspace files) can be downloaded.
-    Downloading is permitted **only** for the purposes of output checking.
-    Request authors are not permitted to download files from their own requests,
-    even if they are also output checkers.
+If all files have been approved, they can be [released](release-files.md)
 
-## Dealing with discrepancies and requested changes to files
+## Re-review of a request
 
-<!-- Output checkers and researchers can add comments on each file group to request
-information and discuss discrepancies. Comments are recorded and displayed on the
-file group with the user's username and a timestamp. -->
+Once a request has been returned, researchers will receive a 
+[notification](../explanation/notifications.md), and can make changes,
+respond to comments and re-submit the request for re-review. Review
+of re-submitted requests follows the same process described above, until
+the request is ready for release.
 
-Researchers should withdraw or update any files that have had changes requested in
-order for their release request to progress. They can add further files, including
-revised versions of problematic files, and then ask the output checkers for further
-review.
 
-Files require approval by two output checkers in order to be released. If the two output checkers 
-do not agree on whether a file should be approved or changes should be requested,
-and there is no way to satisfy the output checker who requests changes, it is possible
-for a third output checker to supply the second approving review.
+---
+* Next: [Release files](release-files.md)

docs/reference/index.md

@@ -3,4 +3,5 @@ The reference provides background knowledge for working with Airlock.
 * [Terms and definitions](terms-and-definitions.md)
 * [Alternative ways to view files](view-files-alt.md)
 * [Viewing underlying source code](view-source-code.md)
+* [Downloading files](downloading-files.md)
 * [Request state diagram](request-states.md)

docs/reference/terms-and-definitions.md

@@ -55,6 +55,18 @@ applied to the files within a file group.
 A stage of the release request process during which the request is considered to be "owned"
 by either the researcher (author) or the reviewer (output checker). 
 
+## Vote (on a request file)
+
+An individual output checker's review of a file. This can be Approved,
+Request changes or Undecided.
+
+## Decision (on a request file)
+
+The combined decision on a file, taking into account all submitted
+reviews from output checkers. This can be Approved or Request Changes
+(if output checkers agree) or Conflicted (if output checkers do not
+agree.)
+
 ## Independent Review
 
 Each time a release request is submitted for review, it is initially reviewed independently by two output checkers. At this stage, output checkers are not aware of the status of other 
@@ -66,3 +78,6 @@ After output checkers have both completed their independent review, there is a p
 consolidation, where they can collaborate and determine the questions and feedback that
 may be required from the researcher, prior to deciding whether this request is now ready
 for release.
+
+At this stage, any Conflicted decision can be discussed and output
+checkers can update their votes. 

mkdocs.yml

@@ -24,8 +24,6 @@ nav:
       - Withdraw a request: how-tos/withdraw-request.md
     - For output checkers:
       - Review a request: how-tos/review-a-request.md
-      - Download a file: how-tos/download-file.md
-      - Reject a request: how-tos/reject-request.md
       - Release files: how-tos/release-files.md
   - Explanation: 
     - explanation/index.md
@@ -38,6 +36,7 @@ nav:
     - reference/terms-and-definitions.md
     - Alternative ways to view files: reference/view-files-alt.md
     - Viewing underlying source code: reference/view-source-code.md
+    - Downloading files: reference/downloading-files.md
     - Request state diagram: reference/request-states.md
 
 watch:

tests/functional/test_docs_screenshots.py

@@ -164,49 +164,97 @@ def do_review(screenshot=True):
             live_server.url
             + release_request.get_url(UrlPath("my-group/outputs/file1.csv"))
         )
+
+        if screenshot:
+            # Screenshot the request file page before voting
+            page.screenshot(path=settings.SCREENSHOT_DIR / "file_review.png")
+
         page.locator("#file-approve-button").click()
+
+        if screenshot:
+            # More dropdown (includes download file option)
+            more_locator = page.locator("#file-button-more")
+            more_locator.click()
+            screenshot_element_with_padding(
+                page,
+                more_locator,
+                "more_dropdown_el_request_file.png",
+                extra={"x": -180, "width": 180, "height": 160},
+            )
+
+            # Click to open the context modal
+            page.locator("button[data-modal=group-context]").click()
+            page.screenshot(path=settings.SCREENSHOT_DIR / "context_modal.png")
+            page.get_by_role("button", name="Close").click()
+
+        if screenshot:
+            # Screenshot the request file page after voting
+            page.screenshot(path=settings.SCREENSHOT_DIR / "file_approved.png")
+
         # Request changes on file2.csv
         page.goto(
             live_server.url
             + release_request.get_url(UrlPath("my-group/outputs/file2.csv"))
         )
-        if screenshot:
-            page.screenshot(path=settings.SCREENSHOT_DIR / "file_review.png")
+
         page.locator("#file-request-changes-button").click()
         # Request changes on summary.txt
         page.goto(
             live_server.url
             + release_request.get_url(UrlPath("my-group/outputs/summary.txt"))
         )
         page.locator("#file-request-changes-button").click()
+
+        if screenshot:
+            # screenshot the tree after voting
+            page.locator("#tree").screenshot(
+                path=settings.SCREENSHOT_DIR / "request_tree_post_voting.png"
+            )
+
         # Submit independent review
         page.goto(live_server.url + release_request.get_url())
+        if screenshot:
+            page.screenshot(path=settings.SCREENSHOT_DIR / "submit_review.png")
+
         page.locator("#submit-review-button").click()
+        if screenshot:
+            page.screenshot(path=settings.SCREENSHOT_DIR / "submitted_review.png")
 
-    # Review as each output checker
+    # Login as output checker and visit pages
     login_as_user(live_server, context, user_dicts["checker1"])
     # Requests index
     page.goto(f"{live_server.url}/requests")
     page.screenshot(path=settings.SCREENSHOT_DIR / "requests_index.png")
     # Request view
     page.goto(live_server.url + release_request.get_url())
     page.screenshot(path=settings.SCREENSHOT_DIR / "request_overview.png")
-    do_review()
+    # File group
+    page.goto(live_server.url + release_request.get_url(UrlPath("my-group")))
+    page.screenshot(path=settings.SCREENSHOT_DIR / "file_group.png")
 
+    # Review as each output checker
+    do_review()
     login_as_user(live_server, context, user_dicts["checker2"])
     do_review(screenshot=False)
 
-    # Add public comments
+    # Add private comment
     page.goto(live_server.url + release_request.get_url(UrlPath("my-group")))
     comment_button = page.get_by_role("button", name=re.compile(r"^Comment"))
     comment_input = page.locator("#id_comment")
-    public_visibility_radio = page.locator("input[name=visibility][value=PUBLIC]")
-    public_visibility_radio.check()
+
     comment_input.fill("Please update file2.csv with more descriptive variable names")
+    page.get_by_test_id("c3").screenshot(
+        path=settings.SCREENSHOT_DIR / "reviewed_request_comment_in_progress.png"
+    )
     comment_button.click()
+    # Add public comment
+    public_visibility_radio = page.locator("input[name=visibility][value=PUBLIC]")
     public_visibility_radio.check()
     comment_input.fill("Is summmary.txt required for output?")
     comment_button.click()
+    page.get_by_test_id("c3").screenshot(
+        path=settings.SCREENSHOT_DIR / "reviewed_request_comments.png"
+    )
 
     # Return to researcher
     page.goto(live_server.url + release_request.get_url())