Making Releases with Maven in Java

What is this article about?

This article is about:

1. What is a release?
2. How are the releases numbered?
3. Why do you need a brunch with the release?
4. Why is release more than just jar (war, ear, zip, etc)?
5. What is a maven-release-plugin?
6. Making a brunch with release: branch.
7. Release preparation with release: prepare.
8. We release using release: perform.

To read and understand this article, I recommend refreshing your knowledge of Maven. Many terms may not be understood without an understanding of this technology.

The first few sections are devoted to the general concept of releases and their numbering. If you are experienced enough, skip it!

What is the release and what it eat

For myself , I define release as fixing a specific set of functionality. Fixing the functionality, you say: "This version of the product contains the ability to create a new document, turn the pages with your finger or launch rockets into space." what your release is able to do, and what it cannot, to say that where the error crept into your system and so on and so forth.
Consider the example of a small project. Let us imagine that the city zoo ordered us to develop a system for monitoring the state of animals: in which enclosures they live, what kind of caretaker cares for them. It is also necessary to inform the caretaker via sms that the animal needs care.
Let the project be done for the Web and has the following structure:
zoo
|---zoo-web
|---zoo-sensor-server

The release for us will be war, which we can upload to the web server, and zip with a small server that receives messages from sensors in aviaries with animals.

Release numbering

“A lot of software version numbering schemes have been created to track software changes,” Wikipedia tells us .
And this is truly so. Most projects, companies, products and individual developers use their version calculating method.
Maven proposes us to use the more or less generally accepted xyz numbering scheme, where:

• x - number of the main functionality of the release
• y - number of additional release functionality
• z - fix bugs number

For example, 1.3.23, 0.7.7 and 1.4.112. We will use it for our zoo.
')

Meanwhile in the zoo

So, we agreed with the Zoo Directorate that before launching a full-fledged product, we will give them three intermediate versions. The first one will contain the implementation of a server that collects information from sensors in aviaries. The web part will be very simple, displaying metrics in unprepared form. The second one will contain a full screen with information on aviaries, sorting capabilities, and so on. The third one will contain the functionality of notifying employees about the necessary actions via SMS. And only when we collect everything, and the client will like everything - we will release the final release.

0.y.0

We give each of the intermediate versions the names 0.1.0, 0.2.0, 0.3.0, respectively.
The first digit is 0, because our main release has not yet come out, this is only an intermediate result.
The second digit is the delivery number. The third is 0, because we believe that there are no bugs at the time of assembly.
When the third digit is 0, it is often not written: 0.1, 0.2, 0.3 .

Alpha, Beta and other RC

Before delivering a release to a client, even an intermediate one, he must go through the QA process. Approaches to release releases for testing may also vary, but in my projects I try to use the concept of Release Candidate.
Before releasing the xy release, you build xy-RC1, xy-RC2, and so on, until QA tells you that the release is stable and ready in UAT or Production.
Then the last RC becomes the most awaited release.

0.1.x

There are errors in any code. And the user will be happy to find them. In the process of support, new bugs are started, you correct them and must provide a version with corrections. For this, bug-fix releases are collected.
For example, you released version 0.1.0, and in the course of real work it turned out that the data of the temperature sensor is not properly processed. Release 0.1.1 is released, which corrects the annoying misunderstanding.

Final release and further

After a series of intermediate deliveries, you collect 1.0-RC, complete the QA process, and collect 1.0. If the customer subsequently wants the functionality of automatically opening the cages at night so that the animals can frolic, you will write and collect 1.1. Find a couple dozen hundred bugs and you will release 1.1.47.
If he suddenly wants to write everything anew, more beautiful and better, then you will most likely need 2.0, then 2.1.45, and so on, and so on.

Release Brunch

So, release is the fixation of functionality. That is, we have created a server to collect data from sensors in aviaries. Made a simple web interface. Tested and gave it all to the zoo, let them put the sensors. We will start to make a beautiful and friendly interface. And of course we will sort everything out.
There are several questions:

1. Where should the new interface code be written?
2. Where we will correct the error in the processing of information from the sensor, if it suddenly found in the zoo?

In the trunk, of course, we have to correct the error. But we cannot assemble a new version in a few days and give it to the zoo. We all disassembled for the sake of a beautiful interface.
Therefore, usually, the release of a release with basic or additional functionality is accompanied by the creation of a branch in VCS (branch). This branch will contain fix bugs found in the current production version of the client. You can do anything in a trunk. And while you always have a stable code that contains only bug fixes.
Usually such a brunch is called <project name> -0.1.x , that is, the brunch of release 0.1, which contains a fix for the bugs of this version.

Why release is more than build war

The end product is not just war on your hands. The product has a life cycle. It should be available for other products. We can build a release again if all the assemblies were lost as a result of a fire in the server zoo.
The release should perform two tasks:

1. Fixing and ensuring the availability of the collected product.
2. Fixing the source code of the release, in case of re-assembly or the start of a new branch from this release.

Thus, you need to find where the collected war and zip for the zoo will lie, as well as to remember at the VCS level that this particular code state corresponds to the release.

Remember the state of the code

For this tag is used. Tags in the version control system, this is the name assigned to the revision. For a custom look, a tag is the same folder as the source code, but its state is fixed at the time the tag is created. And do not use tags as brunches.

We spread the collected product

To store and provide access to the collected product, you can even use the ball on an external server. Maven brings the concept of a repository to industrial development. Artifacts are stored in the repositories, you can take an artifact from the repository. The repository structures artifacts by groups, names and versions.

Together

We need to do:

1. If this is a release of the main or additional functionality, make a branch for fixing bugs.
2. Make a tag to remember the state of the code at the time of release.
3. Make a product assembly and share it.

maven-release-plugin

maven-release-plugin is a tool for interaction between the version control system and the repository, which allows you to execute a release using several commands. The plugin performs for you the entire release process from beginning to end.

Plugin setup

For the plugin to work, it needs the following information in the pom.xml main module of your project:

Version Control Information

First, we need to specify where the source code of the project is stored. For this, the standard Maven tag is used:

 <scm> <connection>scm:svn:http://svn.zoo.com/zoo/trunk</connection> </scm> 

scm: svn: http stands for: use the scm protocol to interact with the svn repository on the http: path. SCM is the Maven protocol for working with version control systems.
If we write a zoo using Mercurial, then we need to write the following:

 <scm> <connection>scm:hg:http://svn.zoo.com/zoo/trunk</connection> </scm> 

Build configuration options

To set the parameters of the release itself, use the plug-in connection in the section.

  <build> <plugins>. 

  <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-release-plugin</artifactId> <configuration> <tagBase>svn://svn.zoo.com/zoo/tags</tagBase> <branchBase>svn://svn.zoo.com/zoo/branches</branchBase> <preparationGoals>clean install</preparationGoals> <goals>deploy</goals> <autoVersionSubmodules>true</autoVersionSubmodules> </configuration> </plugin> 

In configuration:

• tagBase - path to the folder in your repository where tags will be stored.
• branchBase - path to the folder in your repository where the branches will be stored.
• preparationGoals - tasks that need to be performed in preparation for release, before creating a tag. This is usually a standard build cycle.
• goals - tasks that need to be done with the release itself. These are usually integration tests and deployed to a common repository.
• autoVersionSubmodules is a useful setting that allows you to specify a new version for all modules in a project at once.

The plugin also uses the project version:

 <version>0.1-SNAPSHOT</version> 

General requirements

To create a release, it is also necessary to have a client installed on the system for VCS . It must be accessible from the console and be in the PATH (svn, hg, git).
Also, the plugin will not allow you to create a release if you have local modifications in the code. And rightly so!
To create a release, the plugin needs write access to the version control system. Make sure that the authentication cache on your machine has the necessary information or use -Duser = <vcs-user> -Dpassword = <vcs-password>.

Create release zoo-0.1

Let's collect the release of the first delivery for our zoo. We have a trunk with version 0.1-RC3-SNAPSHOT. The QA team told us that RC2 was good enough for us to make a release.

Creating a branch for release - release: branch

This item should be performed only if you are compiling a release with basic or additional functionality. If we had compiled the bug fix release of zoo-0.1.2, then we would have missed this item.
If we are collecting the Release Candidate, then this step is also skipped.
To create a brunch you need to run:

 mvn release:branch -DbranchName=zoo-0.1.x 

During execution, Maven will ask us what the next version is for the trunk, by default offering 0.2-SNAPSHOT.
What is the new working copy version for "Zoo"? (com.zoo:zoo) 0.2-SNAPSHOT:


Release: prepare for release

The pre-release phase in terms of the maven-release-plugin includes checking the project (compilation, tests, build) and creating a tag in the VCS . Tags will be created in the folder specified during configuration.
We will make the release from the created brunch, previously selecting it from the repository. Trunk even at the previous step began to live a new life and do not touch him anymore.

If we collect a bug-fix release, then we don’t need to choose anything. We are already in the bug fixes branch.
If you collect the Release Candidate, then we are performing this phase from the trunk.
Run the following command:

 mvn release:prepare 

Maven will consistently ask us the version number being collected, the name for the tag, and the next version number:
The last question will be answered with 0.1.1-SNAPSHOT, because this is the first future bugfix release.

Release Release: perform

The release phase includes the checkout of the source code from the tag and its assembly (usually before the deploy phase). Yes, just like that, checkout the source code from the tag. Why is this needed if we already have the source code for the working copy? Because Maven wants to be sure that this assembly will be identical to the one that can later be done by manually selecting the tag.
To complete the release you need to run:

 mvn release:perform 

This time they won't ask you anything, they will just do everything they need. The result will be a release posted to the general repository of artifacts.

If something went wrong.

If in the process of using the plugin, something is broken, then you have three options:

1. If it happened due to external factors, for example, the server with the version control system was unavailable, then run the task again. The plugin remembers the last successful action and will try to continue.
2. If the plugin in the process encountered an error of the assembly itself, for example, the integration test failed, use release: rollback , this command will roll back all version changes and remove the failed tags from the version control system
3. If you are sure that there is nothing to roll back, and just want to start again, use release: clean