Difference between revisions of "ESciDoc Release Lifecycle"

From MPDLMediaWiki
Jump to navigation Jump to search
Line 125: Line 125:


== Hints - Deal with errors ==
== Hints - Deal with errors ==
* For testing purposes first start the maven build process with ''-DdryRun = true''. For detailed description see http://maven.apache.org/plugins/maven-release-plugin/prepare-mojo.htm
* For testing purposes first start the maven build process with ''-DdryRun = true''. For detailed description see http://maven.apache.org/plugins/maven-release-plugin/prepare-mojo.html
* If a release fails and the system states that the tag you want to create is already in the svn repository, you have to delete it manually directly in the repository:
* If a release fails and the system states that the tag you want to create is already in the svn repository, you have to delete it manually directly in the repository:
** Open an svn browsing tools like 'kdesvn' for Linux or the 'repo-browser' (right click in SVN Tortoise) for Windows
** Open an svn browsing tools like 'kdesvn' for Linux or the 'repo-browser' (right click in SVN Tortoise) for Windows

Revision as of 10:07, 9 January 2013

Phases of a release[edit]

  • Tag the code in the SCM with a version name
  • Deploy the current documentation to the webserver
  • Deploy the build artifacts to the nexus server
  • Modify the version number in the poms

Identification of a release[edit]

The identification of a release is called version number. In the eSciDoc project these version numbers consist of three decimal numbers separated by dots. If a new release is made, one of these numbers will be incremented.

If the version is a candidate version between two releases, a SNAPSHOT identifier will be appended at the end. So e.g 2.0.18-SNAPSHOT means, the next release version will be 2.0.18. The table below indicates the dependency between software changes and this identification.


X. X. X. -SNAPSHOT

- Milestone changes

- Interface changes

- Greater design changes

- Smaller design changes

- Bugfixes

this indicates it's an intermediate snapshot version


Now if the new version identifier is specified, a release can be performed.

Perform a release[edit]

Before you want to make a release be sure to have the appropriate rights for uploading to the nexus server. Without these rights, a release can not be deployed and fails! Currently there's no way to check the user roles in nexus by a standard user. So you have to ask a nexus administrator, if you have the appropriate rights to deploy releases.

After the rights are validated, you have to decide whether you want to do a release of the complete project or just a single module release.

Project release[edit]

A project release means you want to release everything in the project, every submodule and the parent pom.xml (this is the pom.xml in the root folder of the project). Even submodules which haven't changed are being released. This procedure makes sense, if a lot of submodules have changed and you don't want to release every module one-by-one. If the parent pom.xml has changed you always have to do a project release, since every submodule changes its dependency.

Single module release[edit]

A single module release means you want to release just a single module of a project. This is normally the case, if there are changes just in one or two submodules of a project. Remember that in this release form, you have to take care of the correct inter-project module dependencies by yourself.

For the release itself, there are two possibilities. A graphically assisted release run. Then you would choose Continuum. Or if you prefer a release on the local workstation, do a command line release.

It makes sense to checkout a sources to special release directory in order to avoid an interception with the local svn instance.

Release with Continuum[edit]

At the moment Continuum has some problems with a maven plugin affecting the release mechanism, so the graphical release is not available right now.

Command line release on local workstation[edit]

  • Preparation for scp to work
You need an account with sufficient rights on the machine the website will be deployed (=target machine). Make sure the target machine is contained in the known_host file of your local workstation. This can be achieved by log in successfully via ssh.
On your local workstation generate an rsa key without passphrase using ssh_keygen. Export the public key to the authorized_keys file of the target machine. See ssh. Location of the ssh files on both machines is ~/..ssh.
Check if there's the following section in your ~/.m2/settings.xml
  ...
  <server>
    <id>website</id>
    <!-- ssh username -->
    <username></username>
    <passPhrase></passPhrase>
    <filePermissions>666</filePermissions>
    <directoryPermissions>777</directoryPermissions>
  </server>
  ...
  • Update and commit pubman online download page (svn, target url) with the release specific comments and download links, if needed.
  • Create a new release directory on your local machine and checkout the sources concerned into this directory. Go to the project root folder, if you want to release the whole project; otherwise to the modules root folder). Now type
mvn release:prepare -DpreparationGoals="clean install" -DupdateReleaseInfo=true
Maven proposes a release version for every module concerned (e.g if the last snapshot version is 1.1.5-SNAPSHOT, the default release version proposed is 1.1.5). If a module has been modified, increase the version according the above section. Related modules (e.g cone, cone_presentation, cone_ear) should get the same version. The sources get tagged with a label containing the release version. This information is stored locally in the release.properties file in the directory where the release preparation has been called. Having finished the preparation successfully maven increases the versions in the pom.xml files for the next developement version (e.g if the release version is 1.1.5 the following developement version will be 1.1.6-SNAPHOT)and commits the modified pom.xml to subversion.
  • If you want to discard the release, enter
mvn release:rollback
This will remove the new tag, and rollback the version changes in the pom.xml' files.
  • If the prepare was successful, the release can be performed. Do this by typing:
mvn release:perform
A new repository is created contained in the release repository on nexus as target for the pom.xml and site information. The name of the new repository contains the tag generated by the maven release prepare build. The system now creates all the needed artifacts (jars, javadoc, etc.) for the release and starts the tests. If these were okay, the artifacts will be transfered to Nexus.
  • To publish the snapshot version, you should now do a
mvn clean deploy
This makes the new snapshot version available, so that no developer should have some 'unable to download artifact' errors. ;)

Further information on the release mechanism can be found on the Homepage of the Maven release plugin.

Further steps to do after a release[edit]

  • Update the source tree in your development environment. You get the new SNAPSHOT version in the pom.xml files committed by the maven release:prepare process. Check the version numbers and the versions of the dependencies in the pom.xml files. The version numbers of the dependencies in the pom.xml files are adapted automatically as long as the dependencies belong to the same release process; otherwise they have to be adapted manually. This means: the version numbers of dependencies belonging to e.g. common_services have to be adapted manually in the PubMan pom.xml files.
  • Copy over the released ear to the qa-machine for testing
  • Write an email to escidoc-dev to inform that a new release has been made
  • Clean up the old SNAPSHOT ear on the dev-machine
  • Open a new release in JIRA and close the open release, which you just have released

Publish a release[edit]

  • Copy documentation from escidoc1.escidoc.mpg.de:/srv/www/staging/projects to /escidoc1.escidoc.mpg.de:/srv/www/00_default/projects
  • Copy ear to the appropriate live instance and check the configuration

Special for PubMan release or other applications based on the common services[edit]

  • First make a release of the common_services project as described abaove
  • Before starting the PubMan release adapt in the PubMan pom.xmls the version of the dependencies to jar files of common_services to the new release version.
  • Start the PubMan release
  • When the PubMan release is finished adapt in the PubMan pom.xmls the version of the dependencies to jar files of common_services to the new snapshot version.

Hints - Deal with errors[edit]

  • For testing purposes first start the maven build process with -DdryRun = true. For detailed description see http://maven.apache.org/plugins/maven-release-plugin/prepare-mojo.html
  • If a release fails and the system states that the tag you want to create is already in the svn repository, you have to delete it manually directly in the repository:
    • Open an svn browsing tools like 'kdesvn' for Linux or the 'repo-browser' (right click in SVN Tortoise) for Windows
--Makarenko 16:22, 3 March 2010 (UTC): In kdesvn: File->Open->URL to the repo. (e.g. https://subversion.mpdl.mpg.de/repos/pubman)
    • Simply delete the tag you want to create newly
    • Be careful to not delete the wrong tag!!!!!
  • If you get a strange svn error just do a
svn up
  • If the maven release:perform fails remove the pom.xml and site information in the corresponding release directory on nexus before calling maven release:perform for a second time. Otherwise the upload on nexus will fail.