Permalink
b90f4c0 Jan 3, 2017
@pekkaklarck @jussimalinen
207 lines (131 sloc) 5.72 KB

Creating Robot Framework releases

These instructions cover steps needed to create new Robot Framework releases. Many individual steps are automated, but we do not want to automate the whole procedure because it would be hard to react if something goes terribly wrong. When applicable, the steps are listed as commands that can be copied and executed on the command line.

Using Invoke

Some tasks are automated using Invoke. Generating releases requires it to be installed:

pip install invoke

Invoke is executed from the command line like:

inv[oke] task [options]

Run invoke without arguments for help. All tasks can be listed using invoke --list and they are defined in tasks.py file.

Preparation

  1. Testing

  2. Generate API docs (including JavaDocs) and see is there is something that should be committed:

    doc/api/generate.py
    git diff doc/api
    git commit doc/api -m "Regenerated API docs"   # if needed
    
  3. Repository status

    • Check that you have nothing left to commit, pull, or push:

      git status
      git pull --rebase
      git push
      
    • Clean up:

      invoke clean
      
  4. Set version information to a shell variable to ease copy-pasting further commands. Add aN, bN or rcN postfix if creating a pre-release:

    VERSION=<version>
    

    For example, VERSION=3.0.1 or VERSION=3.1a2.

Release notes

  1. Generate a template for the release notes. Either first create shell variables with GitHub login info or just replace them in the command to actually generate the notes:

    GITHUB_USERNAME=<username>
    GITHUB_PASSWORD=<password>
    
    doc/releasenotes/generate.py $VERSION $GITHUB_USERNAME $GITHUB_PASSWORD >> doc/releasenotes/rf-$VERSION.rst
    
  2. Fill the missing details in the template.

  3. Add, commit and push:

    git add doc/releasenotes/rf-$VERSION.rst
    git commit -m "Release notes for $VERSION" doc/releasenotes/rf-$VERSION.rst
    git push
    
  4. Add short release notes to GitHub's releases page with a link to the full release notes.

Tagging

  1. Tag release:

    invoke tag_release $VERSION
    

    This updates version information in src/robot/version.py and in pom.xml, creates tag, and pushes changes.

  2. Version back to dev:

    invoke set_version --push dev
    

    If you are going to create distributions on the same repository, you may want to post-pone this step until they are done.

Creating distributions

  1. Checkout earlier created tag if necessary:

    git checkout $VERSION
    
  2. Source distribution

  3. JAR distribution

    • Create:

      invoke jar
      
    • Test that JAR is not totally borken:

      java -jar dist/robotframework-$VERSION.jar --version
      java -jar dist/robotframework-$VERSION.jar atest/testdata/misc/pass_and_fail.robot
      
  4. Upload JAR to Sonatype

    • Sonatype offers a service where users can upload JARs and they will be synced to the maven central repository. Below are the instructions to upload the JAR.

    • Prequisites:

      • Install maven

      • Create a Sonatype account

      • Add these lines (filled with the Sonatype account information) to your settings.xml:

        <servers>
            <server>
                <id>sonatype-nexus-staging</id>
                <username></username>
                <password></password>
            </server>
        </servers>
        
      • Create a PGP key

      • Apply for publish rights to org.robotframework project. This will take some time from them to accept.

    • Run command:

      mvn gpg:sign-and-deploy-file -Dfile=dist/robotframework-$VERSION.jar -DpomFile=pom.xml -Durl=http://oss.sonatype.org/service/local/staging/deploy/maven2/ -DrepositoryId=sonatype-nexus-staging
      
    • Go to https://oss.sonatype.org/index.html#welcome, log in with Sonatype credentials, find the staging repository and do close & release

    • After that, the released JAR is synced to Maven central within an hour.

  1. User Guide

    • Create package (updates also library docs):

      doc/userguide/ug2html.py zip
      
    • Update docs at http://robotframework.org/robotframework/:

      git checkout gh-pages
      invoke add_docs $VERSION --push
      git checkout master
      

Announcements

Post-actions

  1. Set version back to dev if you did not do it as part of tagging:

    invoke set_version --push dev
    
  2. Close issue tracker milestone.

  3. Update API doc version at https://readthedocs.org/projects/robot-framework/.