Developer:Using Subversion

From Jig

Branching

The current project repository is laid out as follows:

... + engine
    | + development
    | | + trunk
    | | | + jig-engine
    | | | + jig-demos
    | | | + jig-tests
    | | | + jig-curriculum
    | | | + lib
    | | | + <etc>
    | | + branches
    | | | + working
    | | | | + <branch 1 name>
    | | | | | + jig-engine
    | | | | | + jig-demos
    | | | | | + jig-tests
    | | | | | + jig-curriculum
    | | | | | + lib
    | | | | | + <etc>
    | | | | + <branch 2 name>
    | | | | | + <etc>
    | | | + features
    | | | | + <branch 1 name>
    | | | | | + jig-engine
    | | | | | + jig-demos
    | | | | | + jig-tests
    | | | | | + jig-curriculum
    | | | | | + lib
    | | | | | + <etc>
    | | | | + <branch 2 name>
    | | | | | + <etc>
    | | | + releases
    | | | | + <branch 1 name>
    | | | | | + jig-engine
    | | | | | + jig-demos
    | | | | | + jig-tests
    | | | | | + jig-curriculum
    | | | | | + lib
    | | | | | + <etc>
    | | | | + <branch 2 name>
    | | | | | + <etc>

The structure is useful since the projects are closely related and typically it makes most sense to create a branch that incorporates the entire set of projects as opposed to simply isolating one (e.g., jig-demos).

The difficulty with this approach is that branching in eclipse is a bit challenging. It doesn't work well to check out a branch as a project, but it is not easy to create branches in the style above when the projects have been checked out in the normal fashion.

Thus, it is very useful to use the SVN Repository view in eclipse to manage branching.

The trunk is meant to always contain a usable version of JIG, so modifications should NOT be added directly to the trunk. Instead, modifications should be made on a branch and then merged back on to the trunk.

Making a New Branch

If you're planning to add a specific feature to JIG, your branch should be located in branches/features/<feature name>, if you have a variety of more general changes that you are working on the branch probably belongs in branches/working/<branch name>.

Either way, once you have decided on the branch name and location you are ready to go. In the SVN Repository View in eclipse, open the appropriate parent folders (e.g., branches/working) and then do a right click --> New --> New Remote Folder to create the new branch location (e.g., branches/working/new_graphics_backend)

Now (assuming you want to branch from the trunk) find the projects in the trunk which you will be modifying. For each of these, right click on the project and select Branch/Tag. Change the TO URL field to point to the new branch location. So, for the jig-engine project, the TO URL would point to ...branches/working/new_graphics_backend/jig-engine

Finally, you need to switch back to the package explorer in eclipse and on each of the relevant projects switch to the new branch. Do this by selecting the project, and right click --> Team --> Switch to another branch tag and then enter the newly created branch location for that project (e.g., .../branches/working/new_graphics_backend/jig-engine)

Now you can make any needed changes and when the time comes, these can be merged back onto the trunk as described below.

Merging

Let's say we want to merge the changes from a feature branch back onto the main development line. If the changes from the feature branch are stored in engine/development/my-branch-new-feature/jig-engine and we want to merge onto our main development line stored in engine/development/my-branch/jig-engine

• Begin by checking out a working copy of the main line (.../my-branch/jig-engine)
• Merge from the feature branch into this working copy.
  • In eclipse, select the copy just checked out then right click and select Team-->Merge
  • Update the FROM url, so it points to the feature branch (.../my-branch-new-feature/jig-engine)
  • Select the appropriate starting and ending points