Apache NiFi Release Guidelines

The purpose of this document is to capture and describe the steps involved in producing an official release of Apache NiFi. It is written specifically to someone acting in the capacity of a Release Manager (RM).

The objective

Our aim is to produce an official Apache release from an existing release branch.

Background Material


High level flow of a release

Variable reference substitutions

Throughout this guide, references must be made to names and values that will vary from release to release. For clarity those variable values have been written like Bash variable references. When a term like "/tmp/src/nifi-${NIFI_VERSION}" is seen in an instruction or email template it should be replaced with "/tmp/src/nifi-0.7.0" when working the release of "Apache NiFi 0.7.0".

NOTE: The next version should be the next minor version if the release is based on a major version development branch (e.g master or 0.x). The next version should be the next incremental version if the release is based on a minor version development branch (e.g support/nifi-1.1.x or support/nifi-0.7.4). If this is the first incremental release (e.g. 1.2.1) for a minor release line the support branch may need to be created.

What to validate and how to validate a release

The following is a list of the sorts of things that will be validated and are the basics to check when evaluating a release for a vote.

This list is reflected in the Release Vote and Release Helper Guide emails that are sent once the release has been staged in the Git and Nexus repositories.

The Release Process

The release process includes steps to be performed by the Release Manager as well as the Apache NiFi developer community.

Step 1. Configure the build environment (RM and community)

  1. Follow the steps outlined in the Quickstart Guide to prepare the development system.
  2. Confirm that the local Git workspace is configured with an origin remote pointing to the RM's personal fork of the NiFi source and an "ASF" remote pointing to the Apache Git Repository for NiFi.
     $ git remote -v
     asf    https://git-wip-us.apache.org/repos/asf/nifi.git (fetch)
     asf    https://git-wip-us.apache.org/repos/asf/nifi.git (push)
     origin    https://github.com/${RM_USERID}/nifi.git (fetch)
     origin    https://github.com/${RM_USERID}/nifi.git (push)
    Additional remotes will not cause a problem if these two are correct. Other configurations are perfectly acceptable but the appropriate adjustments to the steps in this guide must be made by the release manager.
  3. Confirm that source code can be checked out for the branch being released.
     git checkout ${BRANCH}
  4. Confirm that the entire application builds correctly in the build environment.

Step 2. Prepare and stage the release (RM)

  1. Create a JIRA ticket for the release tasks for version ${NIFI_VERSION}.
    The resulting JIRA ticket number is referred to as ${JIRA_TICKET} in this guide.
  2. Create the next version in JIRA, if it doesn't already exist, so work can continue towards that release.
  3. Create meaningful release notes for this version if not already created. Enter them here on the NiFi wiki.
  4. Create a new branch off 'master' named after the JIRA ticket.
     $ git checkout -b NIFI-${JIRA_TICKET}-RC${RC} ${BRANCH}
  5. Verify that Maven has sufficient heap space to perform the build tasks. Some plugins and parts of the build consumes a surprisingly large amount of space.
    • These settings have been shown to work for Java 8 for NiFi version 1.x and later.
      $ export MAVEN_OPTS="-Xms1024m -Xmx3076m"
    • And these work for Java 7 for NiFi version 0.x.
      $ export MAVEN_OPTS="-Xms1024m -Xmx3076m -XX:MaxPermSize=256m"
  6. Ensure your settings.xml has been updated to include a signed_release profile and a <server> entry for "repository.apache.org" as shown below. Steps to configure and encrypt Maven passwords. There are other ways to ensure your PGP key is available for signing as well.

                 <gpg.passphrase>GPG passphrase</gpg.passphrase>
                 <password>ENCRYPTED PASSWORD HERE</password>
  7. Ensure the the full application builds and all tests work by executing a parallel (multi-threaded) build.
     $ mvn -T 2.5C clean install -Pinclude-grpc
  8. Startup and test the application with from the root source folder. After a few seconds, NiFi should be up and running at http://localhost:8080/nifi.
     $ cd nifi-assembly/target/nifi-${NIFI_VERSION}-bin/nifi-${NIFI_VERSION}
     $ bin/nifi.sh start
  9. Evaluate and ensure the appropriate license headers are present on all source files.
  10. Ensure LICENSE and NOTICE files are complete and accurate. (Developers should always be keeping these up to date as they go along adding source and modifying dependencies to keep this burden manageable.)
  11. Build the project with the contrib-check profile enabled to validate contribution expectations and find any problems that must be addressed before proceeding.
     $ mvn install -Pcontrib-check,include-grpc

Step 3. Perform the release (RM)

  1. Now its time to have maven prepare the release with this command.
     $ mvn --batch-mode release:prepare \
         -Psigned_release,include-grpc \
         -DscmCommentPrefix="NIFI-${JIRA_TICKET}-RC${RC} " \
         -Dtag="nifi-${NIFI_VERSION}-RC${RC}" \
         -DreleaseVersion="${NIFI_VERSION}" \
         -DdevelopmentVersion="${NEXT_VERSION}" \
  2. Review the release preparation results. If problems are found $ mvn release:rollback will reset the changes, or it may be necessary to run $ mvn release:clean to get the project to a state where it can be rebuilt.

  3. If the preparation without problems, it is time to perform the release and deploy artifacts to staging.

     $ mvn release:perform \
         -Psigned_release,include-grpc \
         -DscmCommentPrefix="${JIRA_TICKET}-RC${RC} " \

    When this completes the artifacts have been released to the Apache Nexus staging repository, a local release branch has been created and there should the staging repository ID returned in a log entry like this.

     [INFO]  * Closing staging repository with ID "orgapachenifi-1088"

    This staging repository ID is referred to by ${STAGING_REPO_ID} in this release guide.

  4. Browse to the Apache Staging Repository and login with your Apache committer credentials and you should see the newly created staging repository listed. If you click on that you can inspect the various staged artifacts.

  5. Validate that all the various aspects of the staged artifacts appear correct

    • Download the sources. Do they compile cleanly? If the result is a build does it execute?
    • Validate the hashes match.
    • Validate that the sources contain no unexpected binaries.
    • Validate the signature for the build and hashes.
    • Validate the LICENSE/NOTICE/Headers.
    • Validate that the README is present and provides sufficient information to build and if necessary execute.
  6. The validated artifacts all look good then push the branch to origin release branch to the ASF repository.

     $ git push asf NIFI-${JIRA_TICKET}-RC${RC}

    From this branch, the ${RC_TAG_COMMIT_ID} will be the 40 byte commit hash with the comment NIFI-${JIRA_TICKET}-RC${RC} prepare release nifi-${NIFI_VERSION}-RC${RC}

  7. Create the signature and hashes for the source release and convenience binary files.

    1. ASCII armored GPG signatures (--digest-algo=SHA512 select the SHA512 hash algorithm). Configure GPG to always prefer stronger hashes.
       $ gpg -a -b --digest-algo=SHA512 nifi-${NIFI_VERSION}-source-release.zip  # produces nifi-${NIFI_VERSION}-source-release.zip.asc
       $ gpg -a -b --digest-algo=SHA512 nifi-${NIFI_VERSION}-bin.tar.gz          # produces nifi-${NIFI_VERSION}-bin.tar.gz.asc
       $ gpg -a -b --digest-algo=SHA512 nifi-${NIFI_VERSION}-bin.zip             # produces nifi-${NIFI_VERSION}-bin.zip.asc
       $ gpg -a -b --digest-algo=SHA512 nifi-toolkit-${NIFI_VERSION}-bin.zip     # produces nifi-toolkit-${NIFI_VERSION}-bin.zip.asc
       $ gpg -a -b --digest-algo=SHA512 nifi-toolkit-${NIFI_VERSION}-bin.tar.gz  # produces nifi-toolkit-${NIFI_VERSION}-bin.tar.gz.asc
    2. Generate SHA1 hash summaries.
       $ shasum -a 1 nifi-${NIFI_VERSION}-source-release.zip | cut -d" " -f1 >  nifi-${NIFI_VERSION}-source-release.zip.sha1
       $ shasum -a 1 nifi-${NIFI_VERSION}-bin.tar.gz | cut -d" " -f1 >  nifi-${NIFI_VERSION}-bin.tar.gz.sha1
       $ shasum -a 1 nifi-${NIFI_VERSION}-bin.zip | cut -d" " -f1 >  nifi-${NIFI_VERSION}-bin.zip.sha1
       $ shasum -a 1 nifi-toolkit-${NIFI_VERSION}-bin.zip | cut -d" " -f1 >  nifi--toolkit${NIFI_VERSION}-bin.zip.sha1
       $ shasum -a 1 nifi-toolkit-${NIFI_VERSION}-bin.tar.gz | cut -d" " -f1 >  nifi-toolkit-${NIFI_VERSION}-bin.tar.gz.sha1
    3. Generate SHA256 hash summaries.
       $ shasum -a 256 nifi-${NIFI_VERSION}-source-release.zip | cut -d" " -f1 >  nifi-${NIFI_VERSION}-source-release.zip.sha256
       $ shasum -a 256 nifi-${NIFI_VERSION}-bin.tar.gz | cut -d" " -f1 >  nifi-${NIFI_VERSION}-bin.tar.gz.sha256
       $ shasum -a 256 nifi-${NIFI_VERSION}-bin.zip | cut -d" " -f1 >  nifi-${NIFI_VERSION}-bin.zip.sha256
       $ shasum -a 256 nifi-toolkit-${NIFI_VERSION}-bin.zip | cut -d" " -f1 >  nifi--toolkit${NIFI_VERSION}-bin.zip.sha256
       $ shasum -a 256 nifi-toolkit-${NIFI_VERSION}-bin.tar.gz | cut -d" " -f1 >  nifi-toolkit-${NIFI_VERSION}-bin.tar.gz.sha256
    4. Generate SHA512 hash summaries.
       $ shasum -a 512 nifi-${NIFI_VERSION}-source-release.zip | cut -d" " -f1 >  nifi-${NIFI_VERSION}-source-release.zip.sha512
       $ shasum -a 512 nifi-${NIFI_VERSION}-bin.tar.gz | cut -d" " -f1 >  nifi-${NIFI_VERSION}-bin.tar.gz.sha512
       $ shasum -a 512 nifi-${NIFI_VERSION}-bin.zip | cut -d" " -f1 >  nifi-${NIFI_VERSION}-bin.zip.sha512
       $ shasum -a 512 nifi-toolkit-${NIFI_VERSION}-bin.zip | cut -d" " -f1 >  nifi--toolkit${NIFI_VERSION}-bin.zip.sha512
       $ shasum -a 512 nifi-toolkit-${NIFI_VERSION}-bin.tar.gz | cut -d" " -f1 >  nifi-toolkit-${NIFI_VERSION}-bin.tar.gz.sha512
  8. For reviewing of the release candidate, commit the source release and convenience binaries files along with their hashes and signatures to https://dist.apache.org/repos/dist/dev/nifi/nifi-${NIFI_VERSION}.

Step 4. Error recovery (RM)

If anything isn't correct about the staged artifacts you can drop the staged repo from repository.apache.org and delete the local tag in git. If you also delete the local branch and clear your local maven repository under org/apache/nifi then it is as if the release never happened. Before doing that though try to figure out what went wrong so the Release Guide can be updated or corrected if necessary.

So, as has been described here you can test the release process until you get it right. The mvn versions:set -Pinclude-grpc and mvn versions:commit -Pinclude-grpc commands can come in handy to help do this so you can set versions to something clearly release test related.

Step 5. Release Vote (RM and community)

After the release source and artifacts are staged in the repositories it's time for the RM to send a release vote to the NiFi community.

Once the release vote is called for, members of the NiFi developer community have 72 hours to evaluate the RC and cast their vote by replying to the "[VOTE] Release ..." email sent by the RM.

NOTE: The release vote is majority rule vote that must include at least 3 binding +1 votes Apache NiFi PMC members and more positive than negative binding votes.

  1. RM sends a vote request email to the NiFi Developers Mailing List.

    • TO: dev@nifi.apache.org
    • FROM: ${RM_USERID}@apache.org
    • SUBJECT: [VOTE] Release Apache NiFi ${NIFI_VERSION}

      I am pleased to be calling this vote for the source release of Apache NiFi nifi-${NIFI_VERSION}.
      The source zip, including signatures, digests, etc. can be found at:
      The Git tag is nifi-${NIFI_VERSION}-RC${RC}
      The Git commit ID is ${RC_TAG_COMMIT_ID}
      Checksums of nifi-x.y.z-source-release.zip:
      SHA1: <40-BYTE-SHA1SUM-HASH>
      SHA256: <64-CHAR-SHA256SUM-HASH>
      SHA512: <128-CHAR-SHA512SUM-HASH>
      Release artifacts are signed with the following key:
      KEYS file available here:
      8 issues were closed/resolved for this release:
      Release note highlights can be found here:
      The vote will be open for 72 hours.
      Please download the release candidate and evaluate the necessary items including checking hashes, signatures, build
      from source, and test.  The please vote:
      [ ] +1 Release this package as nifi-${NIFI_VERSION}
      [ ] +0 no opinion
      [ ] -1 Do not release this package because...
  2. RM sends the following helper email to the NiFi Developers Mailing List.

    • TO: dev@nifi.apache.org
    • FROM: ${RM_USERID}@apache.org
    • SUBJECT: Apache NiFi ${NIFI_VERSION} RC${RC} Release Helper Guide

      Hello Apache NiFi community,
      Please find the associated guidance to help those interested in validating/verifying the release so they can vote.
      # Download latest KEYS file:
      # Import keys file:
      gpg --import KEYS
      # [optional] Clear out local maven artifact repository
      # Pull down nifi-${NIFI_VERSION} source release artifacts for review:
      wget https://dist.apache.org/repos/dist/dev/nifi/nifi-${NIFI_VERSION}/nifi-${NIFI_VERSION}-source-release.zip
      wget https://dist.apache.org/repos/dist/dev/nifi/nifi-${NIFI_VERSION}/nifi-${NIFI_VERSION}-source-release.zip.asc
      wget https://dist.apache.org/repos/dist/dev/nifi/nifi-${NIFI_VERSION}/nifi-${NIFI_VERSION}-source-release.zip.sha1
      wget https://dist.apache.org/repos/dist/dev/nifi/nifi-${NIFI_VERSION}/nifi-${NIFI_VERSION}-source-release.zip.sha256
      wget https://dist.apache.org/repos/dist/dev/nifi/nifi-${NIFI_VERSION}/nifi-${NIFI_VERSION}-source-release.zip.sha512
      # Verify the signature
      gpg --verify nifi-${NIFI_VERSION}-source-release.zip.asc
      # Verify the hashes (sha1, sha256, sha512) match the source and what was provided in the vote email thread
      shasum -a 1 nifi-${NIFI_VERSION}-source-release.zip
      shasum -a 256 nifi-${NIFI_VERSION}-source-release.zip
      shasum -a 512 nifi-${NIFI_VERSION}-source-release.zip
      # Unzip nifi-${NIFI_VERSION}-source-release.zip
      # Verify the build works including release audit tool (RAT) checks
      cd nifi-${NIFI_VERSION}
      mvn clean install -Pcontrib-check,include-grpc
      # Verify the contents contain a good README, NOTICE, and LICENSE.
      # Verify the git commit ID is correct
      # Verify the RC was branched off the correct git commit ID
      # Look at the resulting convenience binary as found in nifi-assembly/target
      # Make sure the README, NOTICE, and LICENSE are present and correct
      # Run the resulting convenience binary and make sure it works as expected
      # Send a response to the vote thread indicating a +1, 0, -1 based on your findings.
      Thank you for your time and effort to validate the release!
  3. Developers in the community review the release candidate and reply to the vote email with their vote.

  4. After 72 hours if

    • at least 3 binding (PMC members) cast +1 votes, and
    • the positive binding votes out number any negative binding votes

    the vote passes and the release candidate is officially released. If the vote does not pass, corrections are made on the release branch and a new release candidate is put forward for a new vote.

  5. RM sends vote result email.

    • TO: dev@nifi.apache.org
    • FROM: ${RM_USERID}@apache.org
    • SUBJECT: [RESULT][VOTE] Release Apache NiFi ${NIFI_VERSION}

      Apache NiFi Community,
      I am pleased to announce that the ${NIFI_VERSION} release of Apache NiFi passes with
        X +1 (binding) votes
        Y +1 (non-binding) votes
        0 0 votes
        0 -1 votes
      Thanks to all who helped make this release possible.
      Here is the PMC vote thread: ${VOTE_THREAD_URL}

Step 6. Finalize the Release

After the vote is complete and the release is approved, these steps complete the release process.

  1. Move convenience binaries and related artifacts from dist/dev to dist/release:
     $ svn move -m "NIFI-${JIRA_TICKET}" https://dist.apache.org/repos/dist/dev/nifi/nifi-${NIFI_VERSION} https://dist.apache.org/repos/dist/release/nifi/${NIFI_VERSION}
  2. In repository.apache.org go to the staging repository and select release and follow the instructions on the site.

  3. Merge the release branch into master.

     $ git checkout master
     $ git merge --no-ff NIFI-${JIRA_TICKET}-RC${RC}
     $ git push asf master
  4. Update Docker version information to point to the next release. For instance, if the next version applied by Maven is 1.3.0-SNAPSHOT, these values should be updated to 1.3.0. This currently consists of two files:

  5. Update the NiFi website to point to the new download(s). Remove older release artifacts from download page (leave the current release and the previous one). For the release just previous to this new one change the links to point to the archive location. See current page as an example of the needed URL changes. In addition to updating the download page as described delete artifacts other than the current/new release from the dist/nifi SVN storage. They are already in the archive location so no need to do anything else.

  6. Update the Migration Guide on the Wiki.

  7. Update the NiFi Web Page to indicate NEWS of the release as appropriate

  8. If the release is on the latest development line, update the NiFi website documentation pages to match the release.

    1. Run the NiFi ${NIFI_VERSION}
    2. Pull down the documentation by running wget -prk http://${host}:${port}/nifi-docs/documentation
    3. Rename the file index file that was generated by running mv ${host}:${port}/nifi-docs/documentation ${host}:${port}/nifi-docs/index.html
    4. Use svn to replace the nifi and nifi-docs folders in https://svn.apache.org/repos/asf/nifi/site/trunk/docs with those in the ${host}:${port} directory pulled down above
  9. In JIRA mark the release version as 'Released' and 'Archived' through 'version' management in the 'administration' console.

  10. Ensure the release artifacts are successfully mirrored to the archive, specifically https://archive.apache.org/dist/nifi/${NIFI_VERSION}/nifi-${NIFI_VERSION}-bin.tar.gz.
    This convenience binary file is the basis for our Docker build and is needed in place before the released tag is pushed to the repository. If there were any issues with the above listed file not being available, it may be necessary to reach out to the ASF Infra team to adjust file size limits to accommodate larger artifacts.

NOTE: The Docker build is triggered by pushing the signed tag in the next step. The release artifacts must be present in the archive before continuing.

  1. Create a proper signed tag of the released codebase based on the RC Tag created during the Maven release process.

    $ git tag -s rel/nifi-${NIFI_VERSION} -m "${JIRA_TICKET} signed release tag for approved release of NiFi ${NIFI_VERSION}" ${RC_TAG_COMMIT_ID}

    For instructions on setting up to sign your tag see here.

  2. Push the release tag to the official ASF repository.

    $ git push asf rel/nifi-${NIFI_VERSION}
  3. Verify that the Docker build began at the Build Status page. If the build does not take place soon after the release tag was pushed, it may be necessary to contact ASF Infra to ask for assistance and the job to be triggered again.

  4. Update the release notes with the final date of the release.

  5. After the release has been complete for 24 hours send the release announcement.

    • See here for an understanding of why you need to wait 24 hours
    • The announcement should addressed as follows.
      • TO: announce@apache.org, dev@nifi.apache.org
      • REPLY-TO: dev@nifi.apache.org
      • FROM: ${RM_USERID}@apache.org
    • The subject should include [ANNOUNCE] Apache NiFi x.y.z release.
    • The text should be based on the template included below.

      The Apache NiFi team would like to announce the release of Apache NiFi ${NIFI_VERSION}.
      Apache NiFi is an easy to use, powerful, and reliable system to process and distribute
      data.  Apache NiFi was made for dataflow.  It supports highly configurable directed graphs
      of data routing, transformation, and system mediation logic.
      More details on Apache NiFi can be found here:
      The release artifacts can be downloaded from here:
      Maven artifacts have been made available here:
      Issues closed/resolved for this list can be found here:
      Release note highlights can be found here:
      Thank you
      The Apache NiFi team