This file outlines the policy on reviews for the Mercury system.
All changes to the Mercury repository, including the compiler, documentation, www pages, library predicates, runtime system, and tools need to be reviewed.
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
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.
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.
We're now posting all diffs to mercury-developers@cs.mu.oz.au.
The reasons for posting to mercury-developers are:
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.
Use the log message you prepared for the review when committing.
The only time changes should be committed before being reviewed is when they
satisfy all of the following conditions:
If the compiler is already broken (i.e. it doesn't pass it's nightly
tests), and your change is a bug fix, then it's not so important to be
absolutely sure that your change won't introduce bugs. You should
still be careful, though. Make sure you review the diffs yourself.
Similarly, if the code you are modifying is a presently unused part of
code - for example a new feature that nobody else is using, that is
switchable, and is switched off by default, or a new tool, or an `under
development' webpage that is not linked to by other webpages yet, the
criteria are a bit looser. Don't use this one too often - only for
small changes. You don't want to go a long way down the wrong track
with your new feature, before finding there's a much better way.
If these conditions are satisfied, then there shouldn't be any problem
with mailing the diff, then committing, then fixing any problems that
come up afterwards, provided you're pretty sure everything will be okay.
This is particularly true if others are waiting for your work.
Usually, a change that has already been reviewed falls into this
category, provided you have addressed the reviewers comments, and
there are no disputes over design decisions. If the reviewer has
specifically asked for another review, or there were a large number of
comments at the review, you should not commit before a second review.
If you are going to commit before the review, use the subject line:
The only time changes should be committed without review by a second
person is when they satisfy all of the following conditions:
These usually don't need to be reviewed by a second
person. Make sure that you review your own changes,
though. Also make sure your log message is more
informative than "fixed a typo", try "s/foo/bar" or
something so that if you did make a change that people
don't approve of, at least it's seen quickly.
Changes to publically visible stuff should always be
reviewed. It's just too easy to make spelling errors,
write incorrect information, commit libel, etc. This
stuff reflects on the whole group, so it shouldn't be
ignored.
Self-Review
Review
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
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'.)
Exceptions: Commit before review
"diff: <short description of change>".
Exceptions: No review
If your change falls into this category, you should still send the
diff and log message to mercury-developers, but use the subject line:
eg: fix typographic errors
fix syntax errors you accidently introduced
fix spelling of people's names
eg: Web pages, documentation, library, man pages.
"trivial diff: <short description of change>".
Last update was $Date: 1997/12/05 02:05:50 $ by $Author: trd $@cs.mu.oz.au.