Work in Progress
This page is work in progress! Do not rely on the information presented here.
Contents
Starting with 2013 there is a new way of getting changes into CACAO. It is intended to get patches faster into the repository and to provide other developers with the possibility to review and discuss the changes before they are accepted.
Overview
The code submission process is designed around the fork/pull-request feature of Bitbucket. Therefore a development repository has been created to stage changes before they are going into the official repository.
Cacao staging-repository:
https://bitbucket.org/cacaovm/cacao-staging/
Development Cycle
First, to participate in this process you will need a Bitbucket account (it's free).
Fork the CACAO staging repository. This Bitbucket manual page explains how to do that. It also shows how to keep in sync with staging repository.
- Clone your CACAO fork.
- Edit and test you working copy and commit it, if everything is fine.
- Push the changeset to your CACAO fork on Bitbucket.
Send a pull-request on Bitbucket. This manual pages explains how to work with pull requests.
The Bitbucket manual contains a page that describes this fork->clone->modify->commit->push->pull request cycle in more detail.
How a pull request gets accepted
Once you sent a pull request everyone can review your changes either online via Bitbucket or clone it on their local machine to compile and test it. Bitbucket offers possibilities to discuss pull requests:
If another developer reviewed your changeset and thinks it is ready to go into the CACAO repository, she can approve it.
If some parts are unclear the issues can be either discussed on pull request basis or even inline.
- If everything is OK one of the CACAO maintainers will accept the pull request and merge the changes into the staging repository.
How to review a pull request
Taken from the manual page: Manually pulling requests to your local system. This assumes you already have a clone of the CACAO repository. In your local checkout do the following:
# Check for incoming changes (changesets from the fork).
$ hg incoming -r default https://bitbucket.org/cacaofan42/cacaofork
# Check for outgoing changes (changesets from your working copy).
$ hg outgoing https://bitbucket.org/cacaofan42/cacaofork
# Pull the changes into the local repository.
$ hg pull -r default https://bitbucket.org/cacaofan42/cacaofork
# Update the working copy.
$ hg update -c tip
# compile, test, ...
# If everything is fine, push the changes up to Bitbucket.
$ hg push
How to update a pull-request
Sometimes there are issues with a pull-request. There are two ways how to handle it.
Create a new commit and update the pull-request
This is the easy way. Fix the problem in your working copy, commit it and push the changes into your CACAO fork. Now you can update the original pull-request using the Edit button on Bitbucket. Note that the problematic changeset is still in the history of the repository but normally this is not a problem.
Send a new pull request
Sometimes you do not want some changeset from a pull-request go into the main repository. Therefore you have to create a new head where the problematic commit is not contained in its history. Push this new head into your CACAO fork and create a new pull-request. Keep the previous changesets in your fork for reference, at least as long as the review is ongoing. Stripping them would invalidate the original pull request.
There are some guild lines you should follow:
Use a prefix of the form [v2], [v3], etc., and the original title in the new pull-request. This help other developers to keep track of your pull-requests.
- Add a link to the original pull-request at the top of the description of the new pull-request.
Mention why there is a new pull-request (possibly referring to the discussion on the original request).
- Also add the original description to the new pull-request.
At the original pull-request, add a comment with a link to the updated request.
- Last but not least, decline the original pull-request.
This procedure might seem somehow complicated but luckily there is an example: Pull-request #2 and the updated version pull-request #3.
Note that this strategy might change depending on the outcome of this bug report.
TODO
List reasons way one would like to do this instead of the easy way, e.g. not used hg mv to move files, etc.
How a changeset should look like
Commit Message
The commit messages should be of the following format:
[module/topic: ]brief description [detailed description/further infos] * path/to/first/file: change description * path/to/second/file: change description
- The first line should be a summary of the commit.
A prefix to mark the module or topic can be added if appropriate, e.g. x86_64: ... for changes to the x86_64 backend or patcher: ... for patcher fixes.
If the commit fixes a bugzilla bug adding the bug id is a good idea, e.g. Fix for PR179: check if jasmin is usable .
- The detailed description can be omitted if the summary is sufficient.
- The commit log should be concluded with list of modified files which a brief description of what has changed.
Remark: The format is based on the GNU Change Log style
Example
darwin: Started populating src/vm/jit/x86_64/darwin, doesn't build yet. Still missing md-os.cpp. * configure.ac: Added darwin. * src/vm/jit/x86_64/Makefile.am: Likewise. * src/vm/jit/x86_64/darwin/Makefile.am: Copied from linux. * src/vm/jit/x86_64/darwin/md-asm.hpp: Likewise. * src/vm/jit/x86_64/linux/Makefile.am: Fixed header/footer. * src/vm/jit/x86_64/linux/md-asm.hpp: Likewise.
Changeset Content
All files in the changeset should comply with the Coding Conventions. Please verify that the boilerplate code is intact and correct (filename, copyright date).
Buildbot
TODO
Buildbot information. Automatic pull-request testing?
Other information
TODO
Copyright assignment?