Review Chats, Comments, and Defects

To start a general conversation about some particular file, open the desired file in the Diff Viewer, type your comment in the Overall section and click Add. Comment could be in plain-text or use rich-text and Markdown formatting, they could also mention other Collaborator users.

To start a conversation about some particular location (line, coordinates, cell), just click the desired location and start typing. The interface will open up automatically and accept your chat message:

To cancel adding a comment or defect, just press Esc. This will clear input text (after confirmation) and will collapse the Chat pane if you were reviewing in Focus Mode.

When you click Add, your message is transmitted to all other users and you have started a threaded conversation for that particular location (line, coordinates, cell). In this case, it would look something like this:

Notice that the conversation is now threaded by line 62 and that a chat icon ( ) now appears next to the source line where the conversation was made.

When you type the name of a file in the same review, it will turn into a link to that file. You can also link to a different line number/s in the current or another text file typing:

line NNN - will create link to desired range of the lines of the current file.

lines N1:N2 - will create link to desired range of the lines of the current file.

[file name]/L:NNN - will create link to line number of the another file. For example, test.txt/L:10

[file name]/L:N1-N2 - will create link to desired range of the lines of the another file. For example, test.txt/L:10-12

When another user chats on that same line, that message appears in yellow and yellow bubbles help make the conversation stand out as needing to be read. The screen updates immediately without the need to refresh the browser:

To answer a message, just type your answer in the chat window.

To clear the "unread chat" state without answering, click the Read button (there is also the Mark all read button at the bottom of the chat pane):

In addition to marking a conversation as read, you can also click the Mark Accepted button in the chat to accept the comment or file revision. The Mark Accepted button affects conversations/revision that is currently displayed in the After pane of the Diff Viewer. The button can be inactive when the revision currently displayed in After pane actually precedes (is earlier than) the revision displayed in Before pane.

"Accept" means whatever you want it to mean.  If you want, you can never use the Mark Accepted button at all. The actual effect of clicking Mark Accepted on a conversation is to mark that conversation as read and to put a green check mark next to that conversation in the Review Material section of the Review Screen. Those check marks are visible to all users.

Conversation status icons in the Review Materials section

Some people use it to mean explicit agreement with the conversation (as opposed to simply not replying, which is implicit agreement).

Many people use "Accept" as sort of a bookmark within the review to keep track of what file revisions they have already looked at and agree with its changes.

• When the author uploads new revision of a document, the accepted icon ( ) will change back to chat icon ( ) denoting that the participant has not yet approved changes in this new revision.

• When the author uploads new revision of a source code or text file Collaborator acts a little bit smarter: if the respective line was not changed, the accepted icon ( ) will keep indicating that the changes were already accepted; otherwise the accepted icon ( ) will change back to chat icon ( ) denoting that the participant has not yet approved changes in this new revision.

When the conversation/revision is already accepted the Mark Accepted button is changed and user can un-accept conversation if it’s needed (e.g., it was accepted by mistake).

Conversation un-accept icon

When user click on un-accept button the accepted icon ( ) will change back to chat icon ( ) and "** Un-Accepted **" comment is added to the conversation.

Conversation un-accept comment

By default comment editing is disabled in order to keep all comments intact for auditing purposes. If the the Allow to edit/delete comments server option is enabled, review participants could modify their own comments. Comment could be modified unless it is followed by another participant's comment.

To edit a comment:

• Mouse-over the specific comment you would like to modify and click Edit.
• Modify comment text and click Save.
  

Review participants could convert only their own comments. Newly created defect is added to the end of conversation, with new date-time.

To convert comment to a defect:

• Mouse-over the specific comment you would like to modify and click Convert to defect.
• Fill proper defect custom fields, modify comment text (if needed) and click Save.
  

Original comment, that was used for defect creation, marked as deleted (strikethrough text of comment).

People have a knack for typing things that for various reasons they should not. Afterwards, they may want to discard their harsh, erroneous or otherwise inappropriate statements.

To discard a comment:

• Mouse-over the specific comment you would like to discard and click Delete.
  

Further behaviour depends on the the Allow to edit/delete comments server option. By default comment deletion is disabled in order to keep all comments intact for auditing purposes. In this case the comment will not be actually deleted, but it will be displayed in a much more difficult to read manner. This styling is meant to deter the casual reader from actually reading the text.

When the Allow to edit/delete comments option is enabled, a confirmation dialog is displayed and on agreement the comment is deleted permanently. Comment could be deleted unless it is followed by another participant's comment.

You cannot undo discarding/deleting a comment. System administrators are allowed to discard any comments. Regular users are allowed to discard their own comments.

User can attach external files (e.g., screenshots, logs, etc.) to the comment. Attachments are added as links to the text of comments.

When a user clicks on the attachment’s link and Collaborator can render attached content, then Collaborator displays the context in the new tab of Web browser. Otherwise, Collaborator suggests to download the attached file. Files of restricted types cannot be attached. User can delete the attachment by editing comment.

When you want to indicate that there is a problem that needs to be fixed rather than simply discussed you open a defect. Do this using the Add as defect button below the comment field:

Besides the comment text, defects can be assigned to a specific participant, as well as have any number of additional fields. These are all completely configurable by the system administrator and can also vary depending on the review workflow that was originally selected for the review. Because this is completely configurable, this manual cannot say exactly what the fields will be or what they mean; ask your administrator for details. It is common to see fields like Severity, Type, Checklist items, and Phase-injected.

Once the defect is created, it is displayed in the Defect Log and Review Material sections of the Review Screen and in the Chat section of current file. The defect conversation is threaded. Open defects are denoted by red icon :

Every defect is given a unique number on the server; in the example above the number is D9. There will only ever be a single defect numbered D9, no matter how many defects, documents or reviews exist on the server.

You can have any number of defects on a single line; all will be logged into the list beneath the chat area.

The word "defect" has many connotations that are inappropriate for peer review. This does not mean the problem will be mirrored in an external issue-tracking system, and it does not necessarily mean it was a bug! Even "bad documentation" can be a defect. A "defect" is just a way of identifying something that needs to be fixed. Moreover, if the word "defect" has a negative connotation in your environment, your Collaborator administrator can change it to another term.

Later, after the author has attempted to fix the defects and has uploaded the new files to the review, the reviewers will verify that the fixes do fix the defect and do not open more defects in the process.

When the fix is verified, locate the defect and click the Mark Fixed button in the defect pane.

The defect icon will change to green to denote that the defect have been fixed. Comments about a defect’s activities (status change etc.) are attributed to the upload version against which the defect was created. The new state of the defect will be reflected in the Defect Log and Review Material sections of the Review Screen and in the Chat section of current file.

If the defect has re-appeared again in some subsequent revisions, you can reopen it by pressing the Reopen button in the defect pane.

To modify defect information click the Edit button in the defect pane.

In the edit mode, you can change defect description and modify other defect custom fields. Also you can move the defect to external issue tracker (see next section for details on this). All of these activities will be logged into the chat conversation area as an audit trail of what happened.

Sometimes you decide that a defect should be fixed at a later date. You do not want to mark it fixed because it is not fixed yet. But you do not want to delete it either because it is still a defect.

In this case you can move the defect to the external issue-tracking system and mark the defect as external. This special state tells everyone else that (a) the review can be completed but (b) the problem was not fixed during the review and (c) how to find the external issue for further auditing.

You may either create the issue (ticket, work item) manually and link it afterwards, or create new item directly from Collaborator and link it automatically. The latter requires, that your Collaborator administrators setup and configure issue-tracking integration.

• To link the defect to some existing issue (ticket, work item), press Track externally and specify the defect identifier in your external issue tracking system.

  

• To create a new issue (ticket, work item), press Export issue and specify the defect details in the ensuing dialog.

  

Any of these actions changes the state of the defect from "Open" to "Tracked Externally".

The defect icon will change to blue to denote that the defect have been tracked externally. The new state of the defect will be reflected in the Defect Log and Review Material sections of the Review Screen and in the Chat section of current file.

Sometimes people could create defects by mistake and may want to delete them afterwards.

It is tempting to delete a defect once the author has corrected the problem, but this is the wrong thing to do. You want to keep the defect record around, just mark it "fixed". Delete a defect only if it turns out that it really was not a defect at all.

To delete a defect click the Delete button in the defect pane.