build version ing and release management

8/3/2019 Build Version Ing and Release Management

1/5

Build Versioning and Release Management

Ray Gebbie

Macys.com Release Engineering

During the release build process, it is crucial to include proper versioning. This is neededin order to be able to clearly identify the artifacts from each build, in order to insure that

the correct version of each artifact has been deployed. The Site Build teams will be able

to know what version has been deployed and will be able to find the exact artifacts thatwere deployed. Also, the QA teams will be able to know which build version they are

testing, and will be able to know that a problem found still exists in that version.

Developers benefit because they can identify the exact source files used in a build, whichhelps in determining what may have changed from previous builds that introduced new

problems.

Key Features

Each artifact must include both external and internal versioning:

External The build output files need to include versioning in their name, especially

the release version, the unique build within the release, and in most cases,the specific Subversion revision number used when performing the build.

Internal Files that include Manifests should include the release version and

Subversion revision within the Manifest. Also, each application should

have a method of displaying the build version information when runningthe application. For example, on the Source of the homepage for the

macys and bloomies applications is included the application build version,

the content build version, and other information.

Release VersionsThe Release Version values that we use vary as to the kind of release it is. We have Code

releases, which are full builds of the whole application, including both Content and

Common Code changes. These releases us a two-digit release number, such as 63.0 or64.0. These release numbers increment by one (or occasionally by .1 for special

releases). The starting value was the first macys release from years ago.

Creative Releases are simply updates to the Creative Content that occur weekly (for

bloomies, they may occur less often). The Common Code is not changed for thesereleases. They are based on the previous code release. The Release Version for these

releases has the base Code release for the first two parts of the release version, and add a

third part, which is the current Macys/Bloomies Marketing week number, which startswith 1 at the start of each fiscal year. So Creative Release 64.0.6 is based on the 64.0code release, and is for Marketing Week 6.

Another part is added to the Release Version for the build number. Keep in mind that if

the release is a Code Release, then the build number is the third part, and if it is a

Creative Release, the build number is the fourth part. Code Build version 64.0.10 isRelease Version 64.0 and Build 10. Creative Build version 64.0.6.5 is Release Version

64.0.6 and Build 5.

Page 1 of 5 11/29/2011


2/5

External Versioning

Each build output file should include the following information:

Release version

This is normally the branch name, but can vary. So we provide this information in a file

called build_versions, that is located at the top level of the wds repository. This file isaccessed during the build and use for the release version throughout the build. It is a

text file that contains a line similar to:

rel-version=

An additional line is added for cases (like creative releases) where the macys and

bloomies build versions are different due to using a different code base. The additionallines can be either of:

bloomies.rel-version=

macys.rel-version=

For trunk and project branches, the value can be just the branch name.

Incremental build number

For each buildable target, which includes jars, ears, and other miscellaneous targets, wekeep an incremental build number that starts with 1 for the first build of that target on a

particular branch. These values are stored as properties on the build_versions file on that

branch. This value is included after the version number in the filename of the outputfrom the build. This value is very useful (along with the Subversion revision) to uniquely

identify each copy of the build output file. As part of the build, when it has completed,

this property is incremented.

Subversion revision

This value is included in the versioning in order to allow developers and Site Buildpeople to be able to go to Subversion and see exact which files were used for the build. It

is the revision that the working copy used for the build was based on. It is always listed

with an r before it in the name of the output file.

Versioned output file names

To show how these elements are used in the output file naming, here are examples of a

macys application and assets build:

macys_64.1.8_r62532.ear

macys_assets_64.1.8_r62532.tar.gz

macys_ops_scripts_64.1.8_r62532.tar.gz

macys_ops_scripts_assets_64.1.8_r62532.tar.gz

For this build, the release version is 64.1, the build number is 8, and the Subversion

revision is 62532. For any other build, there would be similar naming.

The output files are copied to a directory under/release on the build server, in a

subdirectory named//. These files would be put in/release/macys/64.1. In order to make things easier for setting up Anthill workflows, the

build control scripts will also create links to each file with LATEST used in place of the

Page 2 of 5 11/29/2011


3/5

build version info. This allows the name of the artifacts to not have to be changed for

each build. For the above files, here are the links:

macys_LATEST.earmacys_assets_LATEST.tar.gz

macys_ops_scripts_assets_LATEST.tar.gzmacys_ops_scripts_LATEST.tar.gz

If a deploy of a specific build that is not the latest build is needed, then the artifactswould have to specify the real file names, or the deploy can be done manually using the

deploy scripts directly instead of through Anthill.

Internal Versioning

There are two types of internal versioning: updating the Manifest in jar and ear files, andthrough specific code in the application that displays the version info.

Manifest info in jar and ear files

The builds of jars and ear files includes creation of a Manifest file. Inside of that file is

included a lot of information about the files. In jar files, the following info has beenadded for versioning purposes:

Release: SVNRevision:

For example, these lines are from the MANIFEST.MF file in the one of the built versions

of jar file CommonUtil.jar.

Release: 64.1SVNRevision: 61180

We dont keep track of specific build numbers for jar files, since each built jar is

committed into Subversion.

For ear builds, the information in the Manifest is similar, but the Release entry alsoincludes the build number, since ear files are not committed into source control. Thefollowing is from a bloomies ear build on trunk:

Release: trunk.2013SVNRevision: 62416

(The release version is trunk for non-release-branch builds. The build number is 2013).

Application versioning

This is information about the version of the build that is displayable when running an

application. At this point, we only have this available in the macys, bloomies, and POS

applications. This feature should be expanded to other applications, such as the mobile

apps, midtier, and Operational Emails.

For the current application that have this information, it is part of the file index.jsp, which

is created during the docroot build. This file is the jsp that produces the Home Page,

and if the user does View -> Source when the Home Page is displayed, this information

will be seen at the bottom of the Home Page source:

Content Version: Revision: Content Build Date:

Page 3 of 5 11/29/2011


4/5

Application Version: Build:

Application Build Date:

SVN Revision:

The reason there are two sets of values, for Content and Application, is that the Contentbuild is the actual rendering of the jsps (the docroot) build. The Application build is

the creation of the ear file, which includes the latest content build. These builds usuallyhappen close together, but sometimes the Content build is not done because there are no

changes to the Content files, but a new ear build is done to pick up changes in theCommon Code.

Here is an example of this information for a Creative Release for Macys:

Content Version: 63.0.7 Revision: 62430

Content Build Date: Tue Mar 09 02:21:33 PST 2010

Application Version: 63.0.7 Build: 2

Application Build Date: Tue Mar 09, 2010 02:44 PSTSVN Revision: 62430

Note that the Application version is not available when the index.jsp is created in the

docroot build, so tokens are left for the Application information. When the ear is built,the Application build values are substituted for the tokens.

Other Build Requirements

The following are miscellaneous guidelines about builds that should be followed in order

to insure that the Site Build team will be able to build and deploy them under good

Release Management practices.

Build output directory

The directory that the artifacts are built into must be settable from the command line. It

should have a default value that would be used for developer builds. Currently,

depending on the build, release builds set either the target.dir property or the build.dirproperty to a temporary directory on the build server. Then after the build is done, thebuild control scripts look into that location to find the output files. The reasons for letting

the build control scripts specify the build output directory instead of using the default

output directory is that if the default is in the working copy, the output files will be lost ifthe working copy is removed after the build.

Default build output directory

It is highly recommended that the default value for the build output directory not be a

directory within the working copy. This is poor build management practice. When

builds are done this way, the working copy cannot be used again for builds without

clearing out all of the local files that were created by the previous builds. I have foundcases where the Subversion status command does not show all of the directories and

files left from previous builds, so they would have to be found manually and cleared out.If they are not cleared out, they might effect the next build. There was a case where the

next builds succeeded when the same build would fail using a clear working copy, which

caused difficulty in reproducing the build failure so that it could be diagnosed and fixed.Note that creation of any local files in the working copy, not just build output files, is

discouraged for the same reasons.

Page 4 of 5 11/29/2011


5/5

The best default for the build output is a directory in the users home directory, such as/targeton Linux. It is also recommended that all of the output files for a

build go into a single output directory, which is consistent with all current builds andsimplifies the deployment scripts, which can find the built files in a single location.

Output file types

The preferred file types used for build output are ear files, jar files, or tar.gz

(gzipped tar) files. Use of other file types, such as zip files. unzipped tar files, etc. is

discouraged. Using the standard types allows for consistency in the deployment scripts,and also optimizes the space requirements and the time to FTP the files between systems.

Management of Build Artifacts

It is important that management of the output from builds be clearly establised. All built

artifacts for a release should be saved until the release has completed. It may benecessary for developers to access earlier builds to assist in debugging problems when

they appear in later builds. The locations for these builds needs to be standardized. Once

a release has completed, the final build that was used for the release must be retained, butearlier builds can be removed. A policy for how long the released builds are retained

must be created.

We store all built artifacts in the/release file system on the build system. There are

subdirectories for each build target, such as/macys and/bloomies for thoseapplications, /midtier_macys, /midtier_bloomies, /macys_pos, /ops_email, etc. for all

other applications. We also save built jar files in /release if they are built separately from

the applications, although this might not be needed since they are also committed to

Subversion.

Summary of Requirements

Use of release.build or other property in the build scripts to designate release buildsversus development builds

Versioned output file names for release builds, including release version, build

number, and Subversion revision

Versioning information included in the MANIFEST files for jar and ear file builds

Versioning information available by the user from running applications

Configurable build output directory

Default build output directory not located in the working copy

No local files created by the build in the working copy

Use standard output file types

Retain all built artifacts until release, after that save the released version of theartifacts.

Page 5 of 5 11/29/2011

build version ing and release management

Documents