Repository Organization and Best Practices

This document describes how the Doctrine repository is organized and how it should be used. This introduction contains a quick summary of the most important parts of the rest of the document.

Summary:

• The trunk continues to be for mainline development of the next release version of Doctrine. You should only use the trunk if you can tolerate occasional breakage.
• If you are using Doctrine in an external project, you should change your externals to point to a release branch at http://svn.phpdoctrine.org/branches/0.9. or http://svn.phpdoctrine.org/branches/1.0.
• Release branches like branches/1.0 are meant to be stable, bugfix-only branches. They are created from trunk when all of the features and major refactoring for a new release are completed, and the new release has reached feature freeze. No new features or any backwards compatibility breakage should ever happen in a release branch; they are purely for bugfixes.
• Any changes you make to a release branch should be merged into the trunk as well.
• Specific release versions get tagged like tags/1.0beta2 or tags/1.0.0. The contents of tags do not change.

Places in the Repository

Trunk

The trunk contains the most up-to-date, cutting edge version of Doctrine. You should be developing in the trunk if:

• you are working on new features, major refactoring, or other large updates. However, see 'Ticket' and 'Experimental' Branches, below.
• the change you are working on is a targeted for a release with no release branch. In other words, you are working on something for a version which has not been feature-frozen yet.
• the change you are working on might not be backwards compatible

Updates made in the trunk may periodically be used to create new release branches, or merged into existing release branches. See 'How to Branch' and 'How to Merge', below.

http://svn.phpdoctrine.org/trunk

'Ticket' and 'Experimental' Branches

Sometimes you may need to make a change that has a high risk of causing breakage, or might take a long time and cause a lot of disruption. In this case you may want to create a branch for yourself in order to minimize the inconvenience to other developers. It can also make it easier to merge your changes back into the trunk or a release branch, because you have more control over what changes have happened in the branch.

A ticket branch is created to deal with the changes required by a specific Trac ticket. These changes are always named using the number of the ticket, and are located in branches/ticket. An example ticket branch url might be: http://svn.phpdoctrine.org/branches/ticket/560.

An experimental branch is created for undertaking a change which is especially time-consuming and/or risky, especially if during that change it may render the codebase unusable by other developers. An experimental branch should have a name which begins with the name of the developer and also includes a descriptive title, like dbrewer-rewrite-doctrine-in-LOLCODE. An example experimental branch url might be: http://svn.phpdoctrine.org/branches/experimental/dbrewer-rewrite-doctrine-in-LOLCODE.

Both ticket branches and experimental branches should be removed by the developer once the work has been merged back into trunk or the release branch.

Release Branches

A release branch is used to manage changes related to a specific minor version of Doctrine, such as 1.0, 1.2, or 22.1 (once Doctrine has been around as long as GNU Emacs).

When a release of a new minor version gets close, a new release branch is created from the trunk. This should only happen when the new release has reached 'feature-freeze' -- in other words, all new features should be complete, and only bugfixes and stability improvements should remain to be done. The only changes that should get made to a release branch are bugfixes which do not change the API. All changes made to the release branch should be merged back to the trunk as well (see 'How to Merge', below).

When the release branch is ready for packaging, a release tag is created with the version number of the release. See 'Release Tags', below, for more details.

After an official release of a minor version, the release branch may continue to be used for bugfixes to that release. Periodically, a bugfix release may be created by creating another release tag.

Release branches should be as stable as possible. As a result, most projects which are dependent on Doctrine will want to point to a release branch or a release tag as their external source.

The current stable release branch is http://svn.phpdoctrine.org/branches/0.9. The 1.0 release branch at http://svn.phpdoctrine.org/branches/1.0 was created prematurely, and will eventually be replaced by a more stable 1.0 release branch once we reach freature freeze for 1.0. Sorry for any confusion this might have caused!

Release Tags

When a release branch reaches a stable state which is ready for wider public release, a release tag is created. Unlike release branches, the contents of release tags do not change and are therefore the most stable choice for use in Doctrine-dependent projects. However, right now the 1.0 release branch is likely to be a better choice until the release of version 1.0.

Example release tags might include:

* tags/1.0beta2 * tags/1.0rc1 * tags/1.0.0 * tags/1.0.1 * tags/1.2.12

How to Branch or Tag

Branching or tagging is as simple as making an svn copy.

# creating a new release branch from trunk
svn cp http://svn.phpdoctrine.org/trunk http://svn.phpdoctrine.org/branches/0.5.1

# creating a new ticket branch from a release branch
svn cp http://svn.phpdoctrine.org/branches/1.0 http://svn.phpdoctrine.org/branches/ticket/560

# creating a release tag from a release branch
svn cp http://svn.phpdoctrine.org/branches/1.0 http://svn.phpdoctrine.org/tags/1.0.24

# removing a ticket branch after you are done with it
svn rm http://svn.phpdoctrine.org/branches/ticket/560

How to Merge

Merging is the process of taking a specific set of changes from one branch and applying them to another branch or to the trunk. The basic process goes like this:

• Have two checked out working copies: one for the source of the merged changes, and one for the target. For example, you might have a checkout of the 1.0 release branch in doctrine/1.0 and a checkout of trunk at doctrine/trunk on your computer.
• Make your changes in the source working copy and check them in, noting the revision you have created.
• Merge the changes into the target working copy, deal with any conflicts, and run unit tests.
• Check the changes to the target working copy, with a message indicating that it was a merge.

The following is an example showing how to merge in the simple case of a one-commit bug fix to a release branch.

# Make your changes to your 1.0 working copy, and then check them in
> cd ~/doctrine/1.0
> svn ci -m "Fixed #587 (deleting records now removes from identity map)"
Transmitting file data ......
Committed revision 3099.

# Go to your trunk working copy and merge in the changes between
# the revision where you started your changes and the revision where 
# they ended
> cd ~/doctrine/trunk
> svn update
> svn merge -r3098:3099 http://svn.phpdoctrine.org/branches/1.0

# Resolve any conflicts that arise, and run the unit tests, and then...
> svn commit -m "Merge r3099 (fixed #587)"