This document discusses a proposed Branching Policy for projects hosted on JBoss Labs and contained in the Labs Subversion source code repository. A source code revisioning repository must have policies surrounding the processes of branching, merging, releases, and nomenclature to maintain order in the repository. This wiki page describes the structures, policies, and nomenclature for the contents of the JBoss Labs source code repository as well as introduces the reader to the basic mechanics of branching and merging using Subversion. The purpose of this document is not to provide a complete tutorial on Subversion. It is meant to give the reader the knowledge required to understand where to work in the Labs repository. This document does, however, give the reader several examples of branching and merging using three differrent types of Subversion clients. The branching examples given demonstrate both the usage of the clients and branching and naming that follows the policies outlined in this document.
Topics discussed:
Project Types and Structures in the JBoss Labs Subversion Repository
Project Branchng Models
The Repository Branch Structures, Policies, and Nomenclature
Branching Mechanics
Steps to create a generic branch using SVN.
Steps to merge changes made to your branch back into the originating branch
How to create a release tag
Release Branch Policies
Release Nomenclature
Marking the release revision ID
Service Pack Branches
How to create a service pack branch
Service pack branch policies
Branch Mechanics Using Clients
Branch Mechanics using Command Line Interface
Branch Mechanics using Eclipse
Branch Mechanics Using IntelliJ IDEA
-
Quick Introduction to Repository Structure
The sections below discuss the various repository branch policies, but first, here's a quick rundown of the different top level branches in our repository. Before you can understand the other topics, you need to be familiar with, at a minimum, the top level branches in the repository. Here they are:
http://svn.labs.jboss.com/admin/ http://svn.labs.jboss.com/trunk/ http://svn.labs.jboss.com/qa/ http://svn.labs.jboss.com/prod/ http://svn.labs.jboss.com/branches/ http://svn.labs.jboss.com/labels/ http://svn.labs.jboss.com/releases/ http://svn.labs.jboss.com/scripts/ http://svn.labs.jboss.com/servicepacks/
{font:courier new/admin } This branch is a private branch that contains various administration files used to configure our repository. It is available only to system administrators.
{font:courier new/trunk } This directory contains the trunk branches of all projects, be they JEMS, Forge, or Labs projects.
{font:courier new/qa } This branch is used for those project which utilize a three level promotion model that constists of promoting releases from trunk to QA to production. This is a branching and promotion model that is option to projects that are hosted on JBoss Labs
{font:courier new/prod } Again, this branch assumes that a project uses a three level promotion model.
{font:courier new/branches } This branch is reserved for any branch that is not trunk, qa, or prod. We'll discuss this section of the repository below.
{font:courier new/labels } This section of the repository is reserved for arbitrary labels. Like the /branches section, it is divided up, further, into categories for the different types of projects hosted on Labs (i.e., forge, jems, and labs). This document discusses the nomenclature required for these labels.
{font:courier new/releases } This section is reserved for release tags. Once a release branch is created it is not to be modified.
{font:courier new/scripts } This section contains scripts to automate the processes surrounding the creation of releases, branches, and service packs.
{font:courier new/servicepacks } This section contains the structures required to maintain service packs for the various projects contained within the Labs source code repository.
-
Project Types and Structures in the JBoss Labs Subversion Repository
There are three types of projects hosted on Labs:
The 'forge' project which is the source code for the JBoss Labs Infrastructure
Mature 'jems' projects which are productized projects which form the JEMS product offering.
There are 'labs' projects which are projects that have yet to attain JEMS status.
The forge Project Type
The 'forge' project is simply the entire source and configuration for the JBoss Labs infrastructure. Individual Labs projects are not concerned with the contents of repository URLs related to the forge. Examples of such urls:
https://svn.labs.jboss.com/trunk/forge https://svn.labs.jboss.com/qa/forge https://svn.labs.jboss.com/prod/forge https://svn.labs.jboss.com/branches/forge
The jems Project Type
These projects are top level projects that have attained membership in the JBoss Enterprise Middleware Stack. Projects in this category include the JBoss Application Server Project, Hibernate, and JBoss Eclipse IDE.
The labs Project Type
Projects which have yet to attain JEMS status are considere labs projects. These projects are all projects that are outside of the JBoss Enterprise Middleware Stack but are hosted on the JBoss Labs infrastructure.
-
Project Branching Models
There are two type of branching models projects may choose from:
A branch per release model
A three level promotion model
The branch per release model is one where the project has long lived releases, like the JBoss Application Server project, and work is being done in multiple release code lines simultaneously. For example, in JBoss AS, we have the 3.x, 4.x, and a 5.x series. Each of these series will have multiple minor releases all of which will have active development in order to either fix bugs or add functionality for the series. For the branch per release model a different branch pattern is used than one that uses the three level promotion model.
The three level promotion model is used by projects such as the JBoss Labs infrastructure which is designed to have a single version of software in production at any single point in time. With a three level model, there is a dev, qa, and prod environment branches. Each of these branches contain the same software but in different stages of development
**
Branch Structure, Policies, and Nomenclature
The /trunk Branch Policy
This directory contains the trunk branches of all projects, be they JEMS, Forge, or Labs projects.
Structure
Currently, this branch contains the following:
https://svn.labs.jboss.com/trunk/forge
https://svn.labs.jboss.com/trunk/jems
https://svn.labs.jboss.com/trunk/labs
In /trunk, you can see the three different types of projects that are contained in our repository. Each of these three types of projects have their own individual branch policies, but for the most part they are identitical. The /trunk designation implies exactly that: It is the tip of the changes contained in our repository. It is the equivalent to HEAD in a CVS repository. Subversion repositories usually refer to the code lines that work on the HEAD as /trunk.
For example, the /trunk/labs/jbosside project's source code trunk is contained in this branch.
Each project type, with the exception of the forge project is divided up into individual projects. Examples include:
https://svn.labs.jboss.com/trunk/labs/jbossrules
https://svn.labs.jboss.com/trunk/jems/jbosside
https://svn.labs.jboss.com/trunk/labs/jbosswiki
Policy
This branch maintains the policy that only Labs administrators can add projects to the /trunk// dir. The structure that is contained under each project is determined by the individual project leads. Not all projects use the same build mechanisms or project directory structures. But, at least, these project's trunks are stored here. So, all the latest modifications are made in these projects. So for example, if you are the lead of the project jbosside you can add, modify, or remove anything in your project dir:
No additional project types (i.e., forge, jems, labs) are to be created or removed without the approval of the JBoss Labs admins and the Technical Board of Directors.
https://svn.labs.jboss.com/trunk/jems/jbosside
Nomenclature
All projects are named with logical names that match that of the project being added and in the proper project type. The type designation for a project is determined by the Technical Board of Directors. So for example, if the project is called JBoss Application Server with a project type of JEMS, then the project name will be:
https://svn.labs.jboss.com/trunk/jems/jbossas
The /qa Branch Policy
This branch is used for those project which utilize a three level promotion model that constists of promoting releases from trunk to QA to production. This is a branching and promotion model that is optional to projects that are hosted on JBoss Labs. Please read the three level promotion model wiki page to see how this process works and the options you have.
Structure
The structure of this branch is almost identical to that of the /trunk branch. The only difference is that this branch will only contain a subset of those projects which utilize a three level promotion model. Projects promote their code from the trunk code line into the QA branch of the same name. For example, if JBoss IDE's project decided now was the time to promote their code into the QA branch for testing, they would merge their code from their trunk branch:
https://svn.labs.jboss.com/trunk/jems/jbosside
into their qa branch:
https://svn.labs.jboss.com/qa/jems/jbosside
Currently, this branch contains the following:
https://svn.labs.jboss.com/qa/forge
https://svn.labs.jboss.com/qa/jems
https://svn.labs.jboss.com/qa/labs
Each project type, with the exception of the forge project is divided up into individual projects. Examples include:
https://svn.labs.jboss.com/qa/labs/jbossrules
https://svn.labs.jboss.com/qa/jems/jbosside
https://svn.labs.jboss.com/qa/labs/jbosswiki
Policy
Projects are only placed in this branch if they have elected to use the three level promotion model. The projects contained in this branch are a subset of those projects that are contained within the /trunk branch. A project cannot be created in the /qa branch unless it first exists in the /trunk branch. In addition, any qa branch of a project must be created by branching the matching project that first exists in /trunk. For example, if JBoss IDE has elected to use the three level promotion model, first, it will have imported its source code into the branch:
https://svn.labs.jboss.com/trunk/jems/jbosside
Then, a branch from /trunk/jems/jbosside will be created. In subversion, this is accomplished by copying a repository url (i.e., https://svn.labs.jboss.com/trunk/jems/jbosside) to another repository URL, such as https://svn.labs.jboss.com/qa/jems/jbosside. By creating the QA branch from the branch contained in /trunk for a project, we maintain history for a project. So, the new branch created in QA will have all historical information contained in the new branch.
Nomenclature
Project names contained within this branch must be identical to their equivalent project in /trunk
The /prod Branch Policy
Again, this branch assumes that a project uses a three level promotion model.
Structure
The structure will be identical to or a subset of the /qa branch.
Policy
Ideally there would only be one commit per release of a project in this branch. For example, JBoss Labs version 1.0.8 consisted of a single commit into the /prod branch. This commit was the result of a single merge from the /qa branch of JBoss Labs. Sometimes this may not occur due to errors or other problems in the merge from /qa to /prod.
Nomenclature
All branches contained in the /prod branch will consist of the same names that are contained within the /qa branch. The branches contained in /prod may be a subset of those contained in /qa.
The /branches Branch Policy
The /branches branch in the JBoss subversion repository is one that has less restrictive policies for both structure and nomenclature. This branch can be used for purposes that are unique to individual developers as well as groups of developers. For example, a project hosted on Labs might decide to have multiple code lines and use different naming conventions for those code lines. The /branches directory in the repository is meant to contain all the custom and unique names for project branches. There is a high level structure that only decends one directory deep beneath the /branches dir (discussed below), but beyond that level, the structure and names are up to the individual project leads to determine.
Additionally, projects may elect to use a branch per task (called a task branch) pattern to resolving individual tasks for a given project. This pattern consists of creating a branch, even if for only one developer to use, which will contain only the modifications required to resolve a given task. This task branch may only exist for a given amount of time before it is merged back into the code line from which the task branch was created. It is in the /branches directory that branches such as task branches may exist. There are some simple rules about the location of projects branches and those rules are discussed below.
Structure
/branches contains (or will contain):
/forge /labs /jems
Which are simply locations for each category of branches. Same structure exists in /trunk, /qa, /prod, /releases, and /service packs. These top three branches exist to categorize code lines contained within the /branches directory. If your project is a /labs project and is found within the /trunk/labs directory, then you will have permission to create branches under your project contained within /branches/labs. The same is true for JEMS projects. If a JEMS project is located, for example in //trunk/jems/jbossas, then committers to that project will have the rights to create and manage branches within the /branches/jems/jbossas directory (or will have the rights as allowed them by the project lead of said project).
Policy
The policy for branches contained within /branches more relaxed than the other top level struture policies. Only the top two directories contained within the /branches dir are controlled. For example:
/branches/labs/kosmos must be named the same as that of the equivalent project in /trunk/labs/kosmos. In other words, the name kosmos must match. There cannot be more projects in /branches than exist in /trunk.
Underneath the /branches/labs/kosmos directory, it is up to the project lead to determine branch structure. Possible examples include:
/branches/labs/kosmos/tasks/frank/kosmos-1533 which might be a task branch corresponding to the JIRA task KOSMOS-1533 the user frank is working on.
/branches/labs/kosmos/experimental-feature-X which might correspond with a branch of the trunk code line to test out an experimental concept that might dramatically affect the code but may also be a technical dead end. A developer for the kosmos project may decide to create this experimental branch to test some of his or her theories.
Nomenclature
This branch is reserved for any branch that is not trunk, qa, or prod. We'll discuss this section of the repository below.
The /labels Branch Policy
This section of the repository is reserved for arbitrary labels. Like the /branches section, it is divided up, further, into categories for the different types of projects hosted on Labs (i.e., forge, jems, and labs). This document discusses the nomenclature required for these labels.
Structure
The top two levels of the /labels directory are identical to that of the /trunk directory. It may only contain all or a subset of the top two directories contained in /trunk. For example:
/labels/jems/jbossas /labels/labs/kosmos /lables/labs/shotoku
Policy
It is up to the individual project leads to determine labelling of their project code lines. It is recommened that every release have a label (which can be placed in either the /releases directory discussed below or the /labels directory). It can be argued that labels are a redundant concept in Subversion since labels are really a branch and a release corresponds more to a revision ID rather than a code line. However, it is up to the project lead to determine the usefullness of labels in their project(s).
Nomenclature
Label names are up to the project leads to determine.
The /releases Branch Policy
This section is reserved for release tags. Once a release branch is created it is not to be notified. Release labels (or tags) have the same structure as the /labels directory above, but permissions on this directory are going to be reserved to project leads. This way, these code lines cannot be modified unless the project lead modifies them (which shouldn't happen!)
Structure
The top two levels of the /releases directory are identical to that of the /trunk directory. It may only contain all or a subset of the top two directories contained in /trunk. For example:
/releases/jems/jboss-4.0.3SP1 /releases/labs/kosmos.0.5 /lables/labs/shotoku-1.0Alpha
Policy
Labels (which are branches) are not to be modified once created. If a Label is created in this directory for a project that is incorrect, the project lead must remove the label. If a label branch is found to have been modified, it should be removed and recreated from the revision from which the label was originally created. This policy is to guarantee that labels are really labels and nothing more. Eventually, hook scripts which enable us to monitor commits to the /labels branch will enable alerts that labels have been modified. Only project leads (or those designated by project leads) will have the ability to create (i.e., modify) in the /releases directory.
Nomenclature
The naming of releases is determined by the individual projects' release naming policies.
The /scripts Branch Policy
This section contains scripts to automate the processes surrounding the creation of releases, branches, and service packs. This directory is currently only to be used by the repository administrators until a Service Pack Process using this repository structure is determined.
Structure
TBD
Policy
TBD
Nomenclature
TBD
The /servicepacks Branch Policy
This section contains the structures required to maintain service packs for the various projects contained within the Labs source code repository.
This directory is currently only to be used by the repository administrators until a Service Pack Process using this repository structure is determined.
Structure
TBD
Policy
TBD
Nomenclature
TBD
The /admin Branch
This branch is a private branch that contains various administration files used to configure our repository. It is available only to system administrators.
**
Branching Mechanics
Steps to create a generic branch using SVN.
Steps to merge changes made to your branch back into the originating branch
**
! How to create a release tag
Release Branch Policies
Release Nomenclature
Marking the release revision ID
**
Service Pack Branches
How to create a service pack branch
Service pack branch policies
**
Branch Mechanics Using Clients
Branch Mechanics using Command Line Interface
Branch Mechanics using Eclipse
Branch Mechanics Using IntelliJ IDEA
-
As part of the discussion I want to walk through:
1. a branch off of the trunk
2a. a merge of a change in the branch to the trunk
2b. a release tag
3a. a service pack sub-branch off of the release tag
3b. a merge from the sub-branch to its parent branch
4. a tag of the service pack branch
using:
Intellij
Eclipse
Command line
Comments