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.
git diffor by creating series of commits and using
git format-patch(see the git documentation for details). You will need to edit the files that format-patch generates to modify the subject line (see below), and to duplicate this line within the e-mail's body. If you create a diff then new files should be appended verbatim to the end of the diff, with descriptions indicating the name of the file.
git format-patchthen you can use
git send-emailto mail them, or attach them to an e-mail normally. It is also possible to use github pull-requests, however we prefer e-mail.
<one-line description (subject)> <overview or general description of changes> <directory>/<file>: <detailed description of changes>
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.
For very small changes, the <overview or general description> can be omitted, but the other descriptions 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. If the bug is in the bug tracker, also include the bug's number for reference.
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 post all diffs to email@example.com.
The reasons for posting to reviews 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 and pushing changes.
The only time changes should be pushed 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:
"diff: <short description of change>".
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 publicly visible things 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.