Reviews

This file outlines the policy on reviews for the Mercury system.


Reviewable material

All changes to the Mercury repository, including the compiler, documentation, www pages, library predicates, runtime system, and tools need to be reviewed.

Review process

  1. Make sure you are working with an up-to-date copy of the module you are using.
  2. If change is a code change, test change. See "Testing" section of coding standards. Testing may take time - don't forget that steps 3, 4 and 5 can be done in parallel.
  3. Create diff - use `cvs diff -u'. New files should be appended verbatim to the end of the diff, with descriptions indicating the name of the file.
  4. Write log message for this change - use template (see below).
  5. Review diff and log message yourself. (see below)
  6. Send to mercury-developers@cs.mu.oz.au, with the subject "cvs diff: <short description of change>". Nominate a reviewer at top of diff (see below).
  7. Wait for review (see below).
  8. Fix any changes suggested.
  9. Repeat above steps until approval.
  10. Commit change (see below).

Log Messages

Use the template that cvs provides.
	Estimated hours taken: _____

	<overview or general description of changes>

	<directory>/<file>:
		<detailed description of changes>
In estimated hours, include all your time to fix this problem - including debugging time.

The description should state why the changes were made, not just what the changes were. All file modifications related to the same change should be committed together, and use the same log message, even over multiple directories. The reason for this is that the log messages can be viewed on a file-by-file basis, and it is useful to know that a small change of a file in a subdirectory is related to a larger change in other subdirectories.

For very small changes, the can be omitted, but the <detailed description> should stay.

If adding a new feature, this is a good place to describe the feature, how it works, how to turn it on and off, and any present limitations of the feature (note that all this should also be documented within the change, as well). If fixing a bug, describe both the bug and the fix.

Self-Review

You should also review your own code first, and fix any obvious mistakes. Where possible add documentation - if there was something you had to understand when making the change, document it - it makes it easier to review the change if it is documented, as well as generally improving the state of documentation of the compiler.

Review

We're now posting all diffs to mercury-developers@cs.mu.oz.au.

The reasons for posting to mercury-developers are:

You should try to match the reviewer to the code - someone familiar with a section of code can review faster and is more likely to catch errors. Put a preamble at the start of your diff to nominate who you would like to review the diff.

Waiting and approval

Waiting for approval need not be wasted time. This is a good time to start working on something else, clean up unused workspaces, etc. In particular, you might want to run long running tests that have not yet been run on the your change (different grades, different architectures, optimisation levels, etc).

The reviewer(s) should reply, indicate any problems that need to be corrected, and whether the change can be committed yet. Design issues may need to be fully justified before you commit. You may need to fix the problems, then go through another iteration of the review process, or you may be able to just fix a few small problems, then commit.

Committing

If you have added any new files or directories, then before committing you must check the group-id and permissions of the newly created files or directories in the CVS repository. Files should be readable by group mercury and directories should be both readable and writable by group mercury. (Setting of permissions will be enforced by the pre-commit check script `CVSROOT/check.pl'.)

Use the log message you prepared for the review when committing.

Exceptions: Commit before review

The only time changes should be committed before being reviewed is when they satisfy all of the following conditions: