JCR - Glossary
- Action comment
- Once the project is in the 'post-review' project state, the project owner gets to perform all the actions required against the project comments and file comments, and to sign them off as completed. When you record that you've completed the action, you may also record an action comment, for example to record the number of the Defect Report you raised in your bug tracking system.
- Baseline
A baseline (also known as a tag) is a name that identifies particular versions of all the files in a project in a source code management system. Baselines or tags are typically used for identifying internal and external releases of your system.
JCR lets you record the baseline that a file set applies to, both as a record and as a guide for other users. Note that this applies only to file sets uploaded as tarballs/zip files - projects based on code in a VCS instead use the standard VCS mechanism to specify the revisions.
- Diff chunk
- A continguous block of the file with changes. Diff chunks are separated by unchanged lines.
- File colour codes
Colours in JCR indicate the changes that have taken place to a file, a line in a file, or within a file line:
Colour coding of diff chunks in files
Colour Meaning White Line or file has not been changed Green Line or file has been added Light green Shows new version of a modified line Red Line or file has been removed Light red Shows old version of a modified line Yellow Shows changes within a modified line
- File comment
- A comment made by a reviewer on a specified line of a single file in the review project. This is the most common type of comment. See also project comment.
- File notes
- Notes that the project owner can add to an individual review file to assist the reviewers. The notes field is on the file attributes tab page of the project administration screen.
- File set
A file set represents the state of a particular source tree at a moment in time. It is either represented as a revision in a repository, or is uploaded to the system as a tarball/zip file containing all the required files, and is usually identified by a baseline (from your Source Code Management system).
Each review project normally has an original file set and a modified file set. If this was a new project, however, you'll only have a modified set.
When using the built-in fileset upload support, file sets can be uploaded specifically for a review project, or you can re-use file sets created for other projects - this is useful if you want to break the review for a large release into several smaller review projects.
- jcrclass
- See links
- jcrfile
- See links
- Links in Notes and comments
Notes and comments (at the project or file levels) can include links to other documents. JCR will automatically render these as URL anchors.
The following link types are available:
http/https: e.g. http://www.python.org/index.html file: e.g. file://///T/Share/directory/file.txt (a typical link to a file on a Windows network share). Note that if you're using Firefox or other Mozilla-based browser, these links won't open unless you relax security for the JCR website - see http://kb.mozillazine.org/Links_to_local_pages_don%27t_work jcrclass: e.g. jcrclass:///MyClassName. Links to a Java class in the current review project (whether selected for review or not) called MyClassName (shows a selection dialog if more than one class matches) jcrfile: e.g. jcrfile:///path/to/AFile.ext. Links to a file in the current review project (whether selected for review or not) with the specified path within the project. Note that JCR isn't smart enough to work out that things like commas and brackets after a URL aren't part of the url, so put a space after your link.
- Modified file set
- A file set representing the state of the source tree after the work has been completed.
- Original file set
- A file set representing the state of the source tree before work started (the 'before' state).
- Original path
A different path in the original file set for a review file.
This mechanism is used when a file has been moved or renamed. In this case, the file is shown as new (i.e. green), since the diff process was unable to find a version of the file in the original file set. By specifying an original path for the file, the diff will be redone against the proper original version of the file, so the diff will now correctly show the changes made.
- Project comment
- A comment made by a reviewer on the project as a whole. This is used for comments that apply to more than one file, e.g. to record style issues in the code being reviewed. Project comments are grouped by thread, which is just a common title for a number of project comments (much like a discussion thread on a message board or an email conversation). See also file comment.
- Project notes
- Notes that the project owner can add to the project to assist the reviewers. The notes field is on the project summary tab page of the project administration screen.
- Project owner
The owner is the person who sets up a review project. He or she is responsible for uploading or selecting the file sets for the project, selecting the files to review, adding project notes and/or file notes, setting different original paths etc.
Note that the owner can assign a project owner delegate, who will from then on have the same rights as the owner.
- Project owner delegate
- A delegate may be assigned by the project owner, and has the same rights as the owner for administering the project. This is useful if the owner may not always be available when needed.
- Project state
JCR projects go through a lifecycle, represented by states. The states (in order) are:
Initial setup: The project has been created, but the file sets haven't yet been selected Generating diffs: All required file sets are now available. JCR is generating diffs for all the files in the project. When this is complete, there's an automatic transition to ... Selecting files: Diffs have been generated, and the project owner selects the files to review Reviewing files: Reviewers review the files in the project, adding comments as required Review meeting: The project owner and reviewers review all comments and files Post-review: The project owner and delegates carry out any actions arising from the review meeting Complete: All actions are complete.
- Repository
- A VCS repository holding the code for one or more projects
- Review comment
- During the review meeting, you review the file comments and project comments made by reviewers, and decide what action needs to be take for each (if any). When you record the action, you may also make a review comment, perhaps to record the detail of the required action, or maybe to record why the comment is incorrect.
- Review meeting
Once all the reviewers have reviewed the code online, or at least thought of plausible excuses for why they haven't done so, the review project gets put into the 'Review meeting' project state. In our organisation, we get the project owner and all the reviewers into a room with a laptop and a projector, and we all go through the comments made by the reviewers - you may choose to do it differently.
In the review meeting stage, you review the comments made, and optionally add review comments on those comments, decide and record what action is required on each comment (if any), and who should be responsible for carrying out that action.
After the end of the review meeting, the project gets put into the 'Post review' project state.
- Review project
- A review project contains a list of files whose code needs to be reviewed. The project owner sets up the project, choosing the original and modified file sets.
- Reviewer
A person who reviews the code in the review project, and makes comments to record any issues found. The reviewer then participates in the review meeting, where the comments are discussed and required actions are decided.
Reviewers may be assigned explicitly in JCR (so that email notifications are sent when the project is ready for review). Note, however, that JCR allows anyone to review a project, regardless of whether they are assigned as a reviewer.
- Revision
- An identifier for a particular version of a project's code inside a repository. Review projects based on code in a vcs must specify 1 or 2 revisions.
- Selection file
A file containing a list of paths to be selected in a review project. The project owner can upload one or more selection files on the Project Admin File Selection page. For each path in the file, if a matching file is found in the list of files with differences, it will be selected for review.
The file format is as follows:
- ASCII text, with LF or CRLF line endings
- Each line represents the path to a file to be selected, starting from the root directory of the project, i.e. the same paths that show on the Project Admin File Selection tab page
- Paths may use either '/' or '' as the path separator
- The path may include or omit a leading '/' or ''.
It's likely that you'd generate this out of either your SCM or your defect and enhancement tracking system (assuming that the 2 are integrated). At work, we've written a script to generate a file list straight from ClearCase and ClearQuest, based on all files changed for a Change Request. If you have some integration between your Source Code Management and Defect Tracking systems, you may be able to do the same. You can add the script to the External Scripts page, so it's easy for everyone to find.
- VCS (Version Control System)
- A Version Control System such as Subversion, which stores multiple revisions of code (also known as Source Code Management systems).