JCR - Project Owner Instructions

Return to contents page

Contents

This page contains information for use by owners (and owners' delegates) of review projects. As the project owner, you drive the whole review process - you are responsible for creating the review project, setting it up ready for the reviewers, guiding and recording during the review meeting, and often for the actions arising afterwards. Just as well it's your code in the first place, otherwise you might feel a little put-upon.

You can also assign a delegate for the project, who will then be able to administer the project on your behalf. The delegate will be able to do anything you can do (except change the delegate).

Readying a Project for Review

The screens below are used to create the project, then get everything set up ready for the reviewers to start reviewing. The states are listed in project states, but the process goes something like this:

Bear in mind that the administrator can do everything a project owner can do to a project, and a few more things besides. If in doubt, check with your JCR administrator.

Create Project page

This page is available from the 'Create project' menu item on the main project page. You need to specify:

  • A name for the project (which must be unique)
  • A repository (either in a VCS, or using the inbuilt support for uploading tarballs/zip files. NOTE: The repository can not be changed after the project is created!
  • The path of the project in the repository (if using Subversion), e.g. /myproject/trunk. Note that this field will suggest matches from your repository after you've typed the first 2 characters: use Enter, Tab or the mouse to select, and Escape to hide the suggestions
  • Optionally, notes about the project. If a notes template has been configured, this will be used to default this field.

Click Submit, and the project will be created. You'll be taken straight to the Project Admin Summary tab page for the project.

Project Admin Summary tab page

This is the lead-in page for administering a project. You get here either by clicking 'Administer' on a project on the Main page, clicking 'Administer' in the menu on the Project page, or directly from the Create Project page.

On this page you can update the project name, and also add a project note - don't forget to click on Update to save your changes. Your notes should provide useful information for the reviewers, e.g.:

  • What work was done, and why
  • Links to your bug and enhancement tracking system
  • Links to other useful information (unit test reports, code coverage reports, static analysis reports like Findbugs or PMD)
  • Any special instructions.

Notes can contain URLs, as well as links to files and classes in JCR - see links in notes and comments.

This is also the page where you change the project's status - the next and previous statuses show as links at the bottom of the page, along with all the status changes made so far for the project. Clicking on the 'Advance' link updates the status after confirming your intentions.

The 'Revert' link is only there to allow you to recover after making a mistake or forgetting to do something important. For example, you might put a project into the Review status, only to find that you've uploaded the wrong baseline/tag - you'd revert the project to 'Selecting files', and upload or attach the correct file set.

You can also assign a delegate for the project, who will then be able to perform all administration tasks, with the exception of being able to change the delegate.

Project Admin File Sets tab page

This page lists the file sets used by the project,and allows you to select new file sets.

The first two sections show details of the original file set and modified file set for the project. JCR presents diffs between the versions of files in the original and modified file sets. Therefore, each project requires a modified file set, and usually also has an original file set (unless all code in the project is new).

When using a repository in a VCS, these sections allow you to specify the original and modified revisions for the project. The following revision types are supported:

  • Number: The associated field must be set to an integer number, e.g. '123', which must match a revision number in the repository
  • Date: The associated set must be set to a date (in yyyy-mm-dd format, e.g. 2009-06-23), or a date/time (in yyyy-mm-dd HH:MM format, e.g. 2009-06-23 09:15). Note that omitting the time implies midnight at the start of the day
  • Head: The most recent version in the repository. Only valid for the modified file set. If selected, this will be replaced (on submit) with the latest revision number from the repository.

NOTE: The project's path in the repository MUST be valid in each revision specified.

When using JCR's support for uploading filesets, this section lists the baseline, upload date and owner of any original file set and modified file set already selected, as well as the names of any other projects using either of the file sets (just for your information). There is a Select link for each of these file sets, which opens the Project Admin File Set Selection pop-up.

Also in this section is a checkbox to indicate that all code for the project is new, i.e. there will be no original file set.

For old projects started prior to JCR 0.6.2, there is also an option to ignore changes to whitespace when generating diffs. This option is ignored for all new projects.

When you're done, click the 'Submit' button. If JCR now has all the file sets it needs for the project, it'll show an indicator here that diffs will be generated on submission of the page, and will start diffing all the files between the file sets. At this point, the project state is set to 'generating diffs'. Depending on the size of your project and the general beefiness of the box it's running on, this can take a little while - the status is shown on the Summary page while diffs are generating.

A couple of other notes on side-effects here. When you regenerate diffs for a project, the diffs for individual files may well have changed - JCR can't know what's still valid, so it applies the following logic:

  • Any original paths on review files are cleared, and the change type for each file reverts to the change type calculated from the diffs
  • Any file comments are moved to line 1 of the file (note that this can only happen if you started reviewing the project, then reverted its status to Selecting Files, and regenerated the diffs)
  • If you changed either of the file sets, any existing review files (and their comments) are deleted.

Note: If there are any errors generating the diffs for the project, you'll see an error message (in red) on the summary page. In this case, you'll have to talk nicely to the system administrator, who will have to revert the project status and check the JCR log to find out why the diffs failed.

Project Admin File Set Selection pop-up

This pop-up is used to select file sets for the project, and also to upload new file sets. It's accessed by clicking on the 'Select' link on the Project Admin File Sets tab page.

This page displays a list of all file sets in the system (other than those already attached to the project), organised by project and their use within the project (original or modified). Click on the 'Select' link next to the file set you want to use.

This page also allows you to create new file sets by uploading a tarball or zip file. Click on the 'Create new file set' link, enter a tag or baseline name to identify the file set, and select the tarball or zip file to upload. You can create the tarball or zipfile youself, using tar cvf mytarball.tar.gz somedirs or zip -r myzip.zip somedirs, or you can use one of the scripts provided - follow the link at the bottom of the page to the external scripts page. See File set tarball for details of the file contents.

After selecting the tarball or zip file, click 'Upload'. The new fileset will be saved, and will now show in the fileset list (without being attached to any project), from where you can select it for your project.

Project Admin Files tab page

../images/files.png

The project administration files tab page

This tab page is only available once diffs have been generated for the project, i.e. once the project state has reached 'Selecting files'. Its purpose in life is to show you all files that have been selected for review in the project, to record important information about them, and to allow selection of other files to include.

Generally, you'll want to review some proportion of the files that have been changed or added since the last review (you may well want this proportion to be 100%). Effectively, this is what you're doing:

../images/reviewFiles.png

File types to be reviewed

There are 2 ways to select files for review: either by manual selection using the Project Admin Files Selection pop-up, or by uploading a selection file. If you have a suitable script to generate the selection file this is a better option - it's both faster and more accurate. You click on 'upload selection file' to show the selection file upload panel, select the appropriate file on the file system, and click on 'upload file'. When the page refreshes, those files will show as selected, and any errors detected in the selection file will be shown in a list above. There's also a link to the external scripts page, on the assumption that you'll probably have a script to generate this selection file.

The alternative way to select files is to click on the 'Add files' link in the header of the second section on the page. This opens the Project Admin Files Selection pop-up, and any files selected in it will be shown with a plus sign. Note that you must click 'Update' to save these changes.

The table in the second section shows all the selected files. The background colour indicates whether the file was changed, added or removed, using the standard file colour codes. Each file shows the file's name and directory. The table can be sorted (both forward and reverse) by any of several criteria, by clicking on the header links. You can view the contents of any file in the list by clicking on its name. This takes you to the File View page for the file. Note, however, that the contents of binary files which have been modified will show only as 'Binary files differ'.

Each file provides the following links:

  • 'Add note'. This displays a text box for adding a file-level note, which can be edited at any time. Note that notes can contain URLs, as well as links to files and classes in JCR - see links in notes and comments. This is a great place to say what's changed in the file, why, and to include links to the unit tests (using jcrfile or jcrclass links) and to things like documentation or code coverage.
  • 'Set original page'. Use this for files that have been either moved or renamed - select the modified version of the file, and click 'Set original path' to display a pop-up to allow searching for the original location or file name. Click 'Select' to use the selected original file as the original path. This will force re-generation of diffs for this file
  • 'Remove'. Use this to remove a selected file, which then shows with a red cross until 'Update' is clicked. Note that you can click on 'Cancel remove' to leave this file attached to the project. The 'Remove all files' link can be used to remove all the files attached to the project
  • The 'Review priority' dropdown - the intention of this is to guide the reviewers to the most important files in the review, especially if you've included a lot of files or if you think there may be problems in certain files. Remember, though, that it's frequently faster to use the 'Set priorities in bulk' - see below.

Note: If the project is in the review state, changing the original path will move any comments for the file to line 1.

You can also set the priorities for more than one file at a time, by clicking on 'Set priorities in bulk'. This shows a form where you can enter a path pattern (using the same wildcards as in the Project Admin Files Selection pop-up), the priority you'd like to set on files matching the pattern, and whether you'd like this to override any existing priorites. Click on 'Apply priority', and the priorities of all matching files will be adjusted. Note that you still have to click 'Update' to save your changes.

Once you are happy with your changes, remember to click 'Update' to save them.

Project Admin Files Selection pop-up

../images/fileselection.png

Dialog for selecting project files

This pop-up is used to select files to be reviewed. It's accessed by clicking on the 'Add files' link on the Project Admin Files tab page.

Enter a search string for the whole file path (case-sensitive), and optionally select the type of file required (Added, Removed, Changed), then click 'Search'. A list of files matching your seach criteria will be displayed. Files already selected for the project include the text '(selected)'.

You can use the following wildcards in the search string:

  • * matches any number of characters
  • ? matches any single character
  • [AaBbCc] matches any single character in this list (in this case A-C or a-c).

Search string examples:

  • * - all files
  • *.java - all Java files
  • */somepackage/*/*.java - all Java files anywhere under somepackage

Select the required files using the checkboxes. You can also use the 'Select all' and 'De-select all' links. When you have made your selection, click either the 'Update project and close' button, which transfers your selection to the Project Admin Files tab page and closes the dialog, or alternatively click the 'Update project' button, which transfers your selection but leaves the dialog open - this way, you can perform new searches.

Clicking on the name of any file opens this for viewing in another window.

Project Admin Reviewers tab page

This page allows you to select reviewers for the project. If notifications are enabled, all reviewers will be emailed when the project is put into Review state.

The table on this page shows all currently-assigned reviewers for the project, including how many comments they have made and their current total review score (the total of all their file review scores). These latter figures are kept up to date during the review process, so at any time it's possible to see how the reviewers are doing.

Clicking the 'Add reviewer' link allows you to assign a new reviewer, including nominating the role the reviewer will play in the project. Click Save to update the reviewer list, or Cancel to do just that. Alternatively, use the Edit and Delete links to modify the review role of an existing reviewer, or to remove a reviewer from the list.

External Scripts page

This page serves to make useful scripts etc. available for download, and to provide documentation on their use. The default version provides basic scripts to create a project tarball from a directory and from a Subversion repository, but the page is completely under the control of the site administrator; it can be customised as required, or changed completely via JCR system configuration (at install time).

Review by Reviewers

While the reviewers are reviewing the code, you shouldn't have much to do (apart from fielding the odd question, but hopefully your code is so clear this won't be required).

However, you are able to update several aspects of the project during this stage, typically to add extra information that will assist the reviewers. You can:

If you need to do more than this, e.g. to change one of the file sets, you'll have to move the project back to the 'Selecting files' state, on the Project Admin Summary tab page.

The Review Meeting

When you're ready to start the review meeting (after all the reviewers have made their initial comments), you first change the status of the project to 'Review meeting'.

During the meeting itself, you'll typically be the one driving JCR. The aim of the meeting is to discuss all the comments made, and decide what action (if any) needs to be taken for each one. The normal flow is something like this:

An alternative to this process is to sort the project page then go to the project comments page, where you can see all comments for the project. This is convenient because they're all shown together, but the page itself can be slow to display if you need to show file context.

At the end of the review meeting, change the project status to 'Post-review'.

After the Review Meeting

After the review meeting has finished (and you've set the project status to 'Post-review'), your task is to complete all the actions decided on in the review meeting, and to record these actions in JCR.

As in the review meeting, you can either do this via the comment dialogs or the project comments page. Using the file or comment dialog, click on 'Record Action'. Check the checkbox to say that you've completed the required actions, optionally enter an action comment, then click Save. Use 'Next comments' to advance to the next thread or file when required. You can also use the 'Show even if no action required' link to toggle between showing all comments and showing only those still outstanding.

Using the project comments page may be faster if you don't need to record comments about the action you took. Not only do all the comments show together, but you can mark a number of comment actions as complete at once (remember to click Submit to save your changes). You can also use the 'Show even if no action required' link to toggle between showing all comments and showing only those still outstanding.

Finally, once you've signed off all comments requiring action, change the project status to 'Completed'. Note that comments marked 'No action required' or 'Comment incorrect' do not need to be signed off - they will not prevent completion of the project.

File Specifications

JCR allows 2 types of file upload - a file set archive (either a gzipped tarballm or a zip file), and a text file listing files to select. This section documents the assumed contents of those files.

NOTE: Most project owners can ignore this section.

File Set Tarball

The file set tarball (which can actually be either a tarball or a zip file) contains all the files in an original file set or modified file set. It is expected to be a gzipped tarball (usually with a .tar.gz extension), which can be unpacked using GNU tar, or a zip file which can be unpacked using unzip.

NOTE: Wherever possible, I suggest you use scripts to prepare project file set tarballs. There are some available from the external scripts page. They're quite basic, but they work, and should be easy to customise.

When unpacking the tarball or zip file, the file's root directory is assumed to be the root directory of the project source tree. Therefore, if your project tree looks like the following:

/stunning-proj-1.23/config
                   /docs
                   /lib
                   /src

you would change to the 'stunning-proj-1.23' directory and create the tarball or zip file from there:

# cd stunning-proj-1.23
# tar cvzf ../stunning-project-1.23.tar.gz *

or alternatively:

# zip -r ../stunning-project-1.23.zip *

An alternative to this is to write a script to export the source tree directly from your source code management system. This is what we now do at work, and it's much better than the above script (because there's never any developer crap in the tree, plus it's easy to get the baseline). A future version of JCR will integrate directly with SCMs.

Selection File List

See selection file for details.