DKPro Core - Release Guide

Versioning

Versioning scheme

We use a three-part versioning scheme.

Snapshots

Snapshot scheme: {Major}.{Minor}.{Maintenance}-SNAPSHOT

The snapshot version is only used in the current working branch of GitHub (master branch).

Major/Minor releases

Release scheme: {Major}.{Minor}.{Maintenance}

When a major or minor release is made from the master branch, the Major and Minor components may be changed. The Maintenance component is set to 0.

Example
  • snapshot version: 0.1.0-SNAPSHOT
  • release version: 0.1.0
  • new snapshot version: 0.2.0-SNAPSHOT

Maintenance Releases

When a maintenance release is made from a branch, the Major and Minor components may not be changed. The Maintenance component is incremented by one. The final component is updated as for major/minor releases.

Example
  • snapshot version: 0.1.0-SNAPSHOT
  • release version: 0.1.0
  • new snapshot version: 0.1.1-SNAPSHOT

Release process

One-time preparation

  1. sign up on Sonatype if you do not have a user there: https://issues.sonatype.org/
  2. ask for a developer to add you in the users list for DKPro Core JIRA Ticket, if you are not there yet
  3. all project artifacts are signed using GPG, and the public key is distributed to hkp://pool.sks-keyservers.net/. For more information, please refer to How To Generate PGP Signatures With Maven
  4. configure your Maven settings.xml by adding your Sonatype user and password as described here

Preparation

  1. GitHub
    1. Create new issue for the new release
    2. Create next milestone
    3. Move all bugs on the to-be-released milestone which were not fixed to the next milestone
    4. In Releases, draft a new release and copy its initial structure from the release notes of the last stable release
  2. Create branch x.x.x for new release (using Mavem)
    1. Be sure that you have git SSH access properly configured so that Maven can automatically connect to github
    2. mvn release:branch -DbranchName=x.x.x
    3. Push changes to the local/master into origin/master
  3. make sure all extra repositories are removed from all POMs (except ukp-oss-model-releases)
  4. make sure all dependencies (except the models) are available on Maven Central
  5. make sure all modules are listed in the following sections of the dkpro-core-asl or dkpro-core-gpl POMs: _modules_, _dependencyManagement_
  6. check for unnecessary dependencies
    1. Fix dependencies
      1. mvn clean dependency:analyze > analysis.txt
      2. All dependencies that are detected Used undeclared must be added (mind to set the scope correctly to save you additional work later)
      3. Dependencies that are detected as Unused declared must be removed or must be marked as used dependencies, in the case they are really used. Models typically fall in this later case, as well as the ...api.parameter module. To mark them as used dependencies, proceed as below: 
        <build>
  <pluginManagement>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <configuration>
          <usedDependencies>
            <!-- api.parameter is used, alghough undetected by byte-code analysis -->
            <usedDependency>de.tudarmstadt.ukp.dkpro.core:de.tudarmstadt.ukp.dkpro.core.api.parameter-asl</usedDependency>
            <!-- Models not detected by byte-code analysis -->
            <usedDependency>de.tudarmstadt.ukp.dkpro.core:de.tudarmstadt.ukp.dkpro.core.opennlp-model-tagger-de-maxent</usedDependency>
          </usedDependencies>
        </configuration>
      </plugin>
    </plugins>
  </pluginManagement>
</build>
    2. Fix scopes
      1. mvn clean compile dependency:analyze-only > analysis.txt
      2. All dependencies that are detected "Unused declared" with scope "compile" must have the scope changed to "test". NOTE: in some situations, changing the scope to "test" will break the compile build. In those cases, the scope should be left as "compile" in spite of the warning message.
      3. Finding the scopes to be changed using pcregrep (recommended):
      4. cat analysis_compile.txt | pcregrep -nM "Unused declared dependencies found:\n\[WARNING\](.*):compile"
      5. If you don't have pcregrep, use the simpler grep (although the results won't be as easy to analyze!):
      6. cat analysis.txt | grep "\(maven-dependency-plugin\|WARNING.*:.*\)" | grep -v ".*:test$" | less

Maven release

  1. make sure the version number in your POM is a -SNAPSHOT version. (This should always be the case for projects under version control.)
  2. commit all changes to GitHub
  3. from the command line, type mvn clean install to test if the build works
    1. if some of the unit tests fails due to the error java.lang.!OutOfMemoryError: GC overhead limit exceeded, try the command mvn -Dmaven.surefire.heap=4g clean install
  4. if this command is successful, type the command mvn -DautoVersionSubmodules=true release:prepare
    1. if some of the unit tests fails due to the error java.lang.!OutOfMemoryError: GC overhead limit exceeded, try the command mvn -Darguments="-Dmaven.surefire.heap=4g" -DautoVersionSubmodules=true release:prepare
  5. when prompted,
    1. enter the current release, such as 1.1.0 for a full release
    2. accept the default scm tag
    3. and enter the next release such as 1.2.0-SNAPSHOT
    4. enter the passphrase for your GnuPG key when prompted.
  6. if you run into problems accessing GitHub or creating the tag, try specifying your username, password and keyname like this. Mind that if you do that on a machine with other users, it may leak your password via the process list and shell history. So better do this on a private machine and clear your history afterwards:
    1. mvn -Dusername={GITHUB-USERNAME} -Dpassword={GITHUB-PASSWORD} -DautoVersionSubmodules=true release:prepare
  7. finally type the command mvn release:perform 1 if some of the unit tests fails due to the error java.lang.!OutOfMemoryError: GC overhead limit exceeded, try the command mvn -Darguments="-Dmaven.surefire.heap=4g" release:perform

Staging phase

  1. close the staging repository
  2. send an email to developers mailing list and ask developers to check if deployed artifacts are correct
  3. release the staging repository as described here

Publish release in GitHub

  1. In Releases, edit the (previously created) draft of the new release, updating the release notes properly
  2. Publish the release

Documentation

  1. Create a new release folder named after the version number (e.g. 1.8.0) under the folder releases in the gh-pages branch of DKPro Core
  2. Create a folder named docs under the new release folder
  3. Go to the core.doc module of the new release and build it
  4. Copy the generated-docs folder contents from core.doc target to the releases/version_number/docs folder of DKPro Core gh-pages branch
    1. This assumes you have the gh-pages branch in a different local repository than the new release branch. Otherwise, use a temporary location to do the copy before switching between branches or tags.
  5. Edit the _data/releases.yml file in the DKPro Core gh-pages branch. Change the new release from unstable to stable, without any automatic links. The next unstable release (SNAPSHOT) should be updated accordingly, with the automatic links. Just follow the templates for stable and unstable releases
  6. Commit DKPro Core gh-pages branch to GitHub with all the changes you've just made.

JavaDoc

For every stable release, Javadoc should be generated. To Generate Javadoc
  1. From the command line in DKPro Core root folder, switch to the tag of the newly created release (use the git checkout commands to choose the proper tag)
  2. Run mvn javadoc:aggregate to generate the javadoc
  3. Copy the newly created target/site/apidocs folder to the releases/version_number folder of DKPro Core gh-pages branch.
    1. This assumes you have the gh-pages branch in a different local repository than the new release branch. Otherwise, use a temporary location to do the copy before switching between branches or tags.
  4. Commit your new folder in Eclipse

Announcement

  • Update GitHub Pages website
    • Update the Project Home page linking the release notes page
    • Update sidebar
    • Update wiki start page
      • Link the release notes page
      • Link the java docs pages for asl and gpl
      • Create the list of components and link it
      • Create the list of models and link it
      • Create the list of supported input/output formats and link it
  • Announce the release on mailing lists (Plaintext format, no HTML, max 70 chars wide):