Skip to content

Making a Release

Jump to bottom Edit New page
Guenter Neumann edited this page Nov 6, 2013 · 1 revision

As shown in the picture below, the EOP repository contains three main branches, namely master, release and gh-pages. The release branch is the branch containing the code that is supposed to be in a production-ready state whereas the master branch is the main branch containing the code to be incorporated into the next release. gh-pages is instead the branch containing the EOP web site generated by the maven site plugin. Developers commit the work done in their private forks into this branch. When the source code in the master branch reaches a stable point and is ready to be released, all of the changes have to be merged back into release and tagged with a release number. The releases are then downloaded from the EOP repository and distributed as zip files and/or maven artifacts. At the end of the procedure the created artifacts will be available from the EOP maven repository (i.e. this operation is done automatically by the maven release plugin) whereas the zip file will be available form the EOP web site.

EOP_Repository

Making a new release involves these steps:

  1. [Creating a new release of the code](#How_to_create_a new_release_of_the_code)
  2. Creating the archive file of the Configuration Files, Models and Resources
  3. Creating the documentation of the new release

Creating a new release of the code

This procedure allows for preparing and deploying the EOP maven artifacts in an “automatic” way (i.e. the maven plugins take care of a number of operations that otherwise should be done manually). At the end of the procedure the maven artifacts will be in the EOP internal artifactory maven repository (i.e. http://hlt-services4.fbk.eu:8080/artifactory) whereas the version of the SNAPSHOT in the master branch will have been incremented (e.g. 0.1-SNAPSHOT will be 0.2-SNAPSHOT) and the releases in the release branch will have been tagged (e.g. v0.1) and their SNAPSHOT suffixes removed.

Before starting the procedure, the following checks need to be performed:

  • Make sure the clone of the repository is update-to-date: git clone https://github.com/hltfbk/Excitement-Open-Platform;

  • Make sure the user and password for the internal repository are in the local maven setting, i.e. .../.m2/settings.xml, like this:

<servers>
  <server>
    <username>...</username>
    <password>...</password>
    <id>hlt-services4.fbk.eu</id>
  </server>
</servers>
  • Make sure the JAVA_HOME variable is probably set (maybe for Mac OS only, no need for Ubuntu).

The following steps will be firstly described and then followed by the commands need to be entered. v0.1 is the placeholder here, which should be replaced by the real release version number (please consider the release numbering policy).

  1. Create a tmp branch from master and switch to it: git checkout -b tmp/v0.1 master;

  2. Change the pom (by removing the SNAPSHOT suffix), commit and tag version, re-change pom (by adding the SNAPSHOT suffix and incrementing the SNAPSHOT version and commit: mvn release:prepare; Note that during this step, the correct release version number and the development version number need to be entered.

  3. Get the tagged version, compile and deploy: mvn release:perform;

  4. Switch back to the master branch: git checkout master;

  5. Merge the version back into master: git merge --no-ff tmp/v0.1; Note that merging the tmp branch into the master branch generating a merge commit (even if it was a fast-forward merge).

  6. Switch to the release branch: git checkout release;

  7. Merge the version back into release but the tagged version instead of the tmp/v0.1 HEAD: git merge --no-ff tmp/v0.1~1; This means merging into release the commit before the HEAD of the branch tmp/v0.1.

  8. Removing the tmp branch: git branch -D tmp/v0.1;

  9. Push everything, branches and tags: git push --all && git push --tags.

The following figures depict the main git operations of the reported procedure:

git_automatic_procedure_1

git_automatic_procedure_2

At the end of the procedure the new release should be available from the release branch whereas its generated maven artifacts should be available from the EOP maven repository: http://hlt-services4.fbk.eu:8080/artifactory/simple/releases/eu/excitementproject/

Note about the Release Numbering Policy can be found in: Release Numbering Policy.

Creating the archive file of the Configuration Files, Models and Resources

Resources like WordNet and Wikipedia as well as the configuration files of the platform, the pre-trained models created training the platform on the data sets and the data sets themselves are distributed in a separated archive file that can be created with the procedure described in the rest of this section. However it should be noticed that the archive must contain internal/external libraries and resources whose licence is compatible with General Public License (GPL) version 3. Others whose licences are not compatible with this one will have to be downloaded and installed separately by users.

Steps to create the archive file and the procedure needed to update the paths in the configuration files

@TODO

Creating the documentation of the new release

For each new release, after following the above mentioned procedure, the release managers should also upgrade the EOP website. The EOP website consists of two different web sites. The first one (i.e http://hltfbk.github.io/Excitement-Open-Platform/) is the entry point containing the static information of the web site (e.g. Contact). Here for static information we mean something that we think doesn't change frequently. It is built by the maven site plugin. The second web site (i.e. https://github.com/hltfbk/Excitement-Open-Platform/wiki/) contains instead what we think we need to change frequently. It is created by the GitHub wikis new editor and it reachable by a link from the entry point web site as well as the EOP code repository. In the next future we are taking into consideration the possibility to use the second web site only that will contain all the needed information but for the time being as said above it consists of two different web sites.

Updating the maven web site

To this aim, after updating the links in the src/site/site.xml file from the previous release number to the new release number and committing the file to the master and release branches, they should:

  1. Switch to the release branch: "git checkout release".

  2. Run "mvn clean", then "mvn package assembly:assembly", and finally "mvn site:site" to generate the website for the new release.

  3. Copy the content of the target/site directory into a backup directory, then switch the branch to gh-pages (via "git checkout gh-pages") and put the content of the backup folder there in the gh-pages branch. This branch should always store the content of the EOP website which is hosted on Github.

  4. Finally, push it: "git add .", then "git commit -m 'The EOP website upgraded for the new release'", and then "git push origin gh-pages"

Updating the GitHub Wiki web site

Differently to the previous case editing the GitHub Wiki pages does not need to use git. In fact GitHub uses the GitHub wikis new editor to manage the wiki pages that is available from the GitHub web interface. An exception to that is when one wants to add new images because GitHub does not allow you to directly upload images in case you would like to insert them in a Wiki page; the next section explain how to do that by git commands.

How to add new images

If you would like to put images in your documentation on the Wiki, please commit them to the wiki-images directory that resides in the EOP distribution's Git repository (in the gh-pages branch):

https://github.com/hltfbk/Excitement-Open-Platform/tree/gh-pages/wiki-images/

Then, go to the Git repository on Github, obtain the raw URL to your image by opening the image and clicking on the button "Raw".

We have committed one sample image here:

https://github.com/hltfbk/Excitement-Open-Platform/blob/gh-pages/wiki-images/Dijkstra.jpg

and got the Raw URL. Now, you may test it by copying and pasting the following line on the Wiki:

![Dijkstra](https://raw.github.com/hltfbk/Excitement-Open-Platform/gh-pages/wiki-images/Dijkstra.jpg?login=amirhmoin&token=53a992d299b7fab693ddf180853951ca)

Please note that this only works if the edit mode of the Wiki page (shown on the top right of the page) is set to Markdown. However, because of the more organized layout of MediaWiki, I've already set this on many pages to MediaWiki. On those pages, we should either simply put the URL of that image (like below) or switch back to Markdown (this requires changing the entire formatting, i.e. syntax for that page):

[https://raw.github.com/hltfbk/Excitement-Open-Platform/gh-pages/wiki-images/Dijkstra.jpg?login=amirhmoin&token=53a992d299b7fab693ddf180853951ca]

Wiki policy

Using Wiki for Open Source Software (OSS) development is still controversial. Although it is a very useful tool, refusing to follow a unified policy will result in an inconsistent documentation. Therefore, please respect the policy defined here. We reserve the right to change this policy at anytime without notifications. Moreover, violation of this policy might result in deletion of your content and/or revocation of your user rights and/or user account for limited or unlimited time.

  1. In order to contribute to the content, you should have a user account.
  2. Please only use English for the documentation.
  3. Try to use proper page titles and avoid creating duplicate pages. Please first check out the previously created pages.
  4. Please do not edit pages without carefully reading them. Do not add your content somewhere in the middle of other irrelevant contents.
  5. Annotate those parts which still need future work, clarification and/or explanation and/or verification with @TODO annotation marks. Please note that not all of such cases are for the upcoming release.
  6. The idea behind using a Wiki, is to be able to quickly develop a large number of inter-linked web-pages in a collaborative manner. Therefore, try to use relevant internal and external links as much as possible. However, please avoid using irrelevant and/or advertising links.

Release Numbering Policy

(K. Fogel, Producing Open Source Software: How to Run a Successful Free Software Project, 2011)

In each new release of a software project a number of previously reported bugs are fixed and on the other hand, a number of new bugs are introduced! Furthermore, new features and configuration options might be added. The purpose of release numbering is two-fold: the numbers should unambiguously communicate the ordering of releases (i.e. by looking at any two releases’ numbers, one can know which came later), but also they should indicate as compactly as possible the degree and nature of the changes in the release. Release numbers are groups of digits separated by dots: e.g. 5.0.1. While the dots are merely separators and not decimal points, some projects like the Linux Kernel Project have exceptionally treated them as decimals, leading to the sequence of releases like: 0.95, 0.96, ..., 0.99, 1.0, etc. However, the convention that the dots are not decimals is now firmly established and should be considered a standard. There is no limit to the number of components (digit portions containing no dots), but most projects do not go beyond three or four.

Most projects have rules about what kinds of changes are allowed into a release if one is only incrementing the micro number, different rules for the minor number, and still different ones for the major number. While there is no set standard for these rules yet, here is one policy which has been followed by a number of successful open source projects. This policy is adapted from the numbering system used by the APR project:

  1. Changes to the micro number only (that is, changes within the same minor line) must be both forward- and backward-compatible. That is, the changes should be bug fixes only, or very small enhancements to existing features. New features should not be introduced in a micro release.

  2. Changes to the minor number (that is, within the same major line) must be backward-compatible, but not necessarily forward-compatible. It’s normal to introduce new features in a minor release, but usually not too many new features at once.

  3. Changes to the major number mark compatibility boundaries. A new major release can be forward- and backward-incompatible. A major release is expected to have new features, and may even have entire new feature sets.

Some projects like the Linux Kernel Project, use the parity of the minor number component to indicate the stability of the software: even means stable, odd means unstable. This applies only to the minor number, not the major and micro numbers. Increments in the micro number still indicate bug fixes (no new features), and increments in the major number still indicate big changes, new feature sets, etc.

In the EOP, we are also going to follow the same policies which are mentioned for the ARP and the Linux Kernel projects for our distribution release numbering.

Add a custom footer
Clone this wiki locally