Forge Philosophy - Terracotta Forge

This page describes the philosophy of the Terracotta Forge.

Intent of Forge

The Terracotta Forge is a collection of tools and services supporting the development of projects related to Terracotta DSO, both by Terracotta and third parties.

The Terracotta Forge will provide the following tools and services for registered projects:

A (shared) Subversion repository with read/write access for registered developers, and anonymous read access to anyone
A set of (shared) mailing lists
Automated build, testing, and deployment of project artifacts
Project-specific web site generation and hosting
A Maven 2 repository for project artifacts, as well as a set of usable Terracotta Maven artifacts

How to use the Forge

Developers may utilize the Terracotta Forge for hosting and managing Terracotta-related projects. Project registration may occur through informal channels, such as Terracotta mailing lists or via verbal request. Registration of a project implies that

the project will be given a location in the Forge Subversion repository,
the project owner will be subscribed to the Forge mailing lists,
and, if desired, the project will be registered for automated build and deployment.

Automatic build/publish/test

The Forge will provide an automated build, testing, and deployment system that heavily utilizes Maven 2. This automated build system iterates through all registered projects and, for each project

Updates the project from Subversion
Compiles, tests, and deploys project artifact(s)
Generates and deploys the web site for the project

There is a configuration file that identifies projects to be automatically built and deployed, and for specifying which projects will have their sites published.

For the initial version, only scheduled builds are supported, and there is no support for triggering builds on events such as Subversion commits.

Project Site Generation

The project's trunk will be the sole source used when generating its site. It does not matter how many branches or release tags have sprung from the project's repository.

The default downloadable artifacts will also come from the trunk. A separate downloads page for the project will list the downloadable artifacts for all bracnhes and releases of the project.. Release notes embedded in the artifacts will take note of dated information between trunk and releases.

Module Versioning

Proper version management of the artifacts produced by Forge projects is crucial to ensure that version number conflicts do not arise and that there is a single, definitive code line that produces any single version of an artifact. If not managed properly, it would be possible for two different branches to both produce the same version of an artifact, and which one was deployed as the "official" version of that artifact would be arbitrary and unpredictable.

For this reason among others, all Terracotta artifacts must use a version number of at least three numeric components (major, minor, and micro), plus a qualifier, e.g. 1.0.2-SNAPSHOT.

Whenever a branch is created for a project, the version number will be carried over to the new branch, and trunk (or wherever the branch is being created from) will have its version number incremented at at least the minor version. For example, if the trunk version of a project is 1.2.3-SNAPSHOT, when a new branch is created it will take the 1.2.3-SNAPSHOT version, and trunk will be incremented to 1.3.0-SNAPSHOT. This ensures that, no matter how many releases are made from a branch, the version numbers will not conflict with anything created from trunk.

Furthermore, Version numbers of TIMs and other Forge artifacts that depend on a particular version of Terracotta must be incremented at the same level of significance as the Terracotta version they depend on. For example, if Terracotta transitions from version 2.5.1 to 2.5.2, then a TIM at version 1.0.1 would change to 1.0.2. Similarly, a transition from 2.5.2 to 2.6.0 would cause the TIM transition from 1.0.2 to 1.1.0, and 2.6.0 to 3.0.0 means 1.1.0 to 2.0.0 for the TIM. The reasoning behind this is that it will prevent version number collisions that might happen otherwise. Most important, when a branch is made for a TIM, the version number on trunk must be incremented at least to the next minor version, e.g. from 1.0.0-SNAPSHOT to 1.1.0-SNAPSHOT.

Version ranges are not supported.

Branching

Each project in the Forge will have its own trunk/tags/branches structure, customary of projects using Subversion. This will allow each project to branch and tag independently of other projects in the Forge, even though they all share the same Subversion repository.

When creating a new branch, it is recommended to use the Maven Release Plugin to create the branch in the Subversion repository and to adjust the version numbers as appropriate. To create a new branch with the Maven Release Plugin, issue the following command from the project trunk directory:

mvn release:branch -DbranchName=my-branch

In this example my-branch is the name of the new branch. Many projects use a version number for the branch name, so you could for example name your branch "1.0" or "2.5".

When you use the release:branch goal to create the branch, Maven will interactively ask you for the version numbers to use on the branch and on trunk. You should specify the version numbers in accordance with the conventions specified above in the "Module Versioning" section.

Projects that have a dependency on any Terracotta artifacts (such as terracotta.jar, tcconfig.jar, etc.) must follow the branching pattern described below.

Synchronization with Main Terracotta Source Tree

The projects hosted on the Forge will be a mixture of Terracotta projects and third-party projects. The Terracotta projects, which are all closely tied to Terracotta DSO, must be certified to work with a particular version of Terracotta. These projects declare a dependency on a particular version of the Terracotta artifacts, such as 2.5.0-SNAPSHOT. Each release branch in the main Terracotta source tree produces a different version of these artifacts. For instance, at the time of writing, trunk produces 2.6.0-SNAPSHOT versions, while the 2.5 branch produces 2.5.x-SNAPSHOT versions.

Effectively, this means that for each release branch in the main Terracotta source tree (e.g. 2.4, 2.5, etc.) there will be a corresponding branch for each project on the Forge. The branch for the Forge project will depend on the version produced by its corresponding branch in the main source tree, and should be named tc-XXX where XXX is the name of the Terracotta branch that this branch is tracking. For instance, the trunk version of the project will depend on Terracotta 2.6.0-SNAPSHOT versions, while the tc-2.5 branch for the project will depend 2.5.0-SNAPSHOT versions.

Although Forge projects may create as many branches as necessary, they will need to have at least one branch for each release branch in the main Terracotta source tree, and thus the number of Terracotta release branches is a lower bound for the number of branches for the project.

Note that this branching scheme is required only for projects which declare a dependency on the Terracotta artifacts, and does not apply, for instance, to things such as skins or some parent POMs.