2016-03 Details: How to Review a Release

Introduction

This document is intended for first-time reviewers of Apache Taverna, particularly those reviewers who desire additional information about the review process and tools used. It assumes you have already read How to Review a Release and Vote.

Contents

• Getting Started
• Verify Your Environment
• Download the Release Candidate
• BEFORE You Unzip the Release Candidate
• AFTER You Unzip the Release Candidate But BEFORE You Build
• Build
• AFTER the (Successful) Build
• Tips
• Definitions

Getting Started

First read How to Review a Release and Vote.

In addition to the prerequisites listed in the README file, you will also need:

• A command line interface (e.g., UNIX Terminal, GitBash (Windows), or PowerShell (Windows).
• GPG - for verifying PGP key signatures. (See download page for Windows and other OS versions. See also Apache verification information and GPG Windows information.)

You may find the following tools useful.

• MD5 and SHA Checksum Utility
• Online Difference Checker (for text files)

Verify your environment

Use the command line interface to verify you have the correct versions of Maven and Java as stated in the README file. Use the following commands to check Maven (mvn) and Java versions.

        mvn --version

        java --version

Download the release candidate

1. Create a temporary directory for the release candidate. (Windows users may want to use a high level directory (e.g., C:/src) to avoid errors caused by long path names.)
2. Open the VOTE email, and click the release candidate link. This will open a web page with four additional links:  .zip (the release candidate),.asc (the signature file), .md5 (the md5 hash file), and .sha1 (the sha1 hash file). (See sections 1a and 1b below for information about signature and hash files.)
3. Download the files to your computer by clicking on each of the four links and saving the files to your computer. (You may need to use Ctrl-S to save a text file from the browser to text. Make sure the browser does not append ".txt" to the file.)

Alternatively, you can use wget to download the release candidate. (See Apache Stratos 3.0.0 Test Procedure.) 

BEFORE you unzip the release candidate

1a. Check that Checksums are valid

There are three sources of checksums:

• The VOTE email, 
• The release candidate .zip file, and 
• The checksum files (.md5 and .sha1), downloaded at the same time as the release candidate.

All three checksums should be identical.

There are two steps: generate and verify. You can use a command line interface or a utility. Both methods are described below.

Check using the command line interface

GENERATE. To generate checksums, navigate to the directory containing the .zip file and run the CertUtil command. Append SHA512 and MD5, as shown below, to generate those checksums.  (The default gives you the SHA1 checksum.) 

        CertUtil -hashfile 'apache-taverna-parent-2-incubating-source-release.zip'

        CertUtil -hashfile 'apache-taverna-parent-2-incubating-source-release.zip' SHA512

        CertUtil -hashfile 'apache-taverna-parent-2-incubating-source-release.zip' MD5

VERIFY. To verify, visually compare the checksums with those listed in the VOTE email, or use an online difference checker.

Check using the MD5 and SHA Checksum Utility

GENERATE. Follow the steps below.

1. Open the MD5 and SHA Checksum Utility (double-click the .exe), a window opens (see below). 
2. Browse to the release candidate .zip file, and the checksums will be displayed. (Use the checkboxes to choose which checksums you want to see.) 
3. You can copy individual checksums, or use the Copy All button. 
   

VERIFY. You can visually compare the checksums or use an online difference checker.  The utiility also allows you to paste a checksum (e.g., either from the VOTE email or from the downloaded .md5 or .sha1 files) into the Hash input box, and the utility will compare it with the value from the .zip file.

1b. Check that the PGP signature is valid

Each software artifact is signed using a PGP (Pretty Good Privacy) key. Verifying the downloaded key matches the original key is a critical step.

You can verify the signatures using a command line interface. See https://httpd.apache.org/dev/verification.html for some general verification info.

Command line interface

1. Download the Taverna key file from https://dist.apache.org/repos/dist/release/incubator/taverna/KEYS. (On Windows this can be done by typing Ctrl-S in the browser window and saving the file as keys.txt.)
   
   
2. Import the key file into GPG:
   

       gpg --import keys.txt

    

3. Download the .asc file. (Save this file in the same folder as keys.txt.)
   
   
4. Verify the .asc file matches the zipped release candidate by using the gpg command with the --verify option followed by the .asc filename and the .zip filename.

              gpg --verify 'apache-taverna-...-source-release.zip.asc' 'apache-taverna-...-source-release.zip'

AFTER you unzip the release candidate, but BEFORE you build

2. Check the commit ID matches the VOTE email

The idea here is to check that the commit ID in the downloaded file matches that in the VOTE email. You will use a command line interface for at least some of these steps.

Approach 1 (clone the git repository, checkout the commit id, and compare to release candidate)

This approach uses Git commands to compare the downloaded release candidate to a cloned git repository. You will clone one copy and unzip the other copy in such a way that will "trick" Git into thinking you are comparing two versions that you have edited.

1. Make a new directory and change to that directory (e.g., mkdir 1 ; cd 1)
2. Git clone that-repository
3. Checkout the commit id from the repository you just created: git checkout <commit_id>
4.  rm -rf*
5. Unzip the release candidate (e.g., apache-taverna-parent-2-incubating-source-release.zip)
6. mv apache-taverna-"/*. (one level up)
7. git status

Git will then review the checksums of every file and let you know what has "changed." 

If there are NO CHANGES, then the commit ID in the VOTE email matches the release candidate.

Approach 2 (download git commit from GitHub and compare to release candidate)

This approach uses the commit id from the VOTE email to download that commit from GitHub, which is then compared to the release candidate using the diff command.

1. Search for the git commit corresponding to the email by browsing for it on GitHub. Use a URL that follows this pattern: https://github.com/apache/incubator-taverna-language/commit/<hash>, where <hash> is the commit hash you want to download. 
2. Click "Download Zip" and save the file to your computer.
3. Make a new directory, change to the new directory
4. Unzip the GitHub file to the new folder. (e.g., mkdir 1 ; cd 1 ; unzip <filename>.zip)
5. Move up a directory level (cd .. ) 
6. Make a second new directory (e.g., mkdir 2)
7. Change to the second new directory (e.g., cd 2) 
8. Unzip the release candidate (e.g., unzip release-candidate.zip)
9. Move up one directory level. (When you do a directory listing you should see both new directories listed.)
10. Compare all files in the two new directories using the diff command:
11. Linix: diff -uR 1 2
12. Windows, GitBash: diff -r 1 2 (Windows CMD command line try FC)

The files that differ will be shown. If you do this after you build, make sure you don't have any target folders before diff-ing. (Run mvn clean to be sure.)

Again, if there are NO DIFFERENCES, then the commit ID in the VOTE email matches the release candidate.

3a. Check the incubator disclaimer (INCUBATOR PROJECTS ONLY)

All Podlings must include a disclaimer indicating they are in incubation. To check a Taverna release candidate, open the DISCLAIMER file (in the top level release candidate folder) and verify the text matches what is shown below. You can use a text editor (e.g., Notepad++) or an integrated development environment (IDE), such as Eclipse, to open the DISCLAIMER files.  

        Apache Taverna is an effort undergoing incubation at the Apache Software 
        Foundation (ASF), sponsored by the Apache Incubator PMC.

        Incubation is required of all newly accepted projects until a further review 
        indicates that the infrastructure, communications, and decision making process 
        have stabilized in a manner consistent with other successful ASF projects.

        While incubation status is not necessarily a reflection of the completeness 
        or stability of the code, it does indicate that the project has yet to be 
        fully endorsed by the ASF.

3b. Check that file names include "incubating"

Check the unzipped release candidate to ensure the top-level distribution folder contains the word "incubating" (Is this all that can be checked before building? See 11 below.)

4. Check the top-level LICENSE and NOTICE files

LICENSE file

Check the text of the LICENSE file in the top-level release candidate folder, and ensure the Apache License matches the text of the required Apache License. The LICENSE file may also include details of additional licenses.

If additional, third-party licenses are listed below the required Apache License, ensure the licenses are allowed in Apache Software Foundation projects. (See also item 9, Check the dependencies - Review binary licenses.)

NOTICE file

Check the text of the NOTICE file in the top-level release candidate folder, and ensure it matches the text below.

        Apache Taverna Language
        Copyright 2014-2016 The Apache Software Foundation

        This product includes software developed at
        The Apache Software Foundation (http://www.apache.org/).

        Portions of this software were originally based on the following:
        - Copyright 2010-2014 University of Manchester, UK
        These have been licensed to the Apache Software Foundation under a software grant.

5. Check the source file headers

Code developed at the ASF

Check that each file has the ASF license header text and no copyright.  The ASF Source Headers web page details how to handle source file headers for code developed at the ASF. In short, the copyright must be removed (see requirements) and files should have the ASF license header text added to the header.

Third-party files

Check that each file has a license and that the license is allowed. Files used by the project, but not submitted by their owners directly to the ASF, are treated differently. Copyright notices stay in the header, and associated licenses must be part of the distribution.

6. Check the provenance

TO DO

7. Check that the source code does not include any binaries

Before building, the downloaded zip folder should contain no unexpected binary artifacts. For example, there should be no *.jar files. 

There may be some "expected" binary files, such as pictures and test workflows. If these come from third-parties (e.g., a Creative Commons-licensed JPEG), they should be declared in NOTICE/LICENSE.

         mvn clean install > console.txt 2> err.txt

         cat target/generated-sources/license/THIRD-PARTY.txt | sort