Branches

Version 24, last updated by Mirco Dotta at December 15, 2011 18:15 UTC

This page has two main goals:

Describe the convention for creating new branches.
Describe the project's workflow.

Project's Structure & Branch Naming Convention

Ideally, the project's directory structure should be close to the following:

master: The main development branch.
experimental: Hosts branches for trying out ideas.
issue: All branches under `issue` are related to an Assembla ticket. The ticket's number must be suffixed to the name of the branch.
platform: Branches for experimental support of future Eclipse platforms (with different JDT). Eric Molitor (emolitor) will be responsible for these forks.
release: Development branches for a target release. Stability is an important requirement for all branches living here.

All branches' names are lowercase and words should be separated using '-' (minus character). Furthermore, all branches under issue must be named using the following scheme: <short description>-<ticket number>.

Workflow

The first thing you should usually do is creating a new branch. It's easy to decide where your branch should live as you are either experimenting a new idea (in which case create it under experimental) or you want to work on a defect/enhancement/feature (in which case create it under issue). If you create a new branch under issue you need a ticket. If you can't find a ticket describing what you want to work on, simply create a new ticket before starting to do any work. For each branch created under issue it is imperative to have a ticket linked to it.

Overall, we expect to have very few (possibly none at all) branches living in experimental, as we would like defect/enhancement/feature to be driven by tickets as much as possible.

When you create a new branch under issue, you should try to push your branch remotely as soon as possible. Don't be afraid of sharing bad code, none will blame you for that. The only moment when code quality does matter is when you are about to merge your changes into the mainline (master branch). Until that moment you are free of committing almost anything on your own branch.

When you are done working on a ticket (you have cleaned up the code and you made sure it compiles against scalac 2.8.x, 2.9.x and 2.10), it is time to create a code-review request and ask in the ide-dev mailing list for a reviewer. There is no formalized strategy for producing a code-review request at the moment, so it's up to you as long as it is easy for the reviewer to carry out the job.

Once the review process is over, you are good to merge. But before doing so, you need to know on what branches you should merge to. In general, you will always need to merge with master. Though, depending on the ticket you have been working on, you may also need to merge in one of the branches under release.

A new release branch is created when it is time to start working on stabilizing the Scala IDE for a final release. At the time of this writing, for example, work is being done for releasing 2.0.0. Consequently, when working on a ticket with its Milestone set to 2.0, you will always need to merge your work with both master and scala-ide-2.0.x. If the ticket's Milestone is not 2.0, you may still be allowed to merge in the scala-ide-2.0.x release branch, depending on the content of your changes. The best way to know whether you should merge in a release branch is to open a discussion in the ide-dev mailing list.

The following are the steps you should follow when your work is ready to be integrated in the mainline:

merge your branch into master (and in a release branch if needed. Look at the ticket's Milestone field),
close the ticket, and
delete the remote branch associated with the above closed ticket.

Now you are ready to hack on a new ticket ;)

If anything above is unclear, please make sure to ask in the ide-dev mailing list for clarification.