...

1. Create a [DISCUSS] thread on dev@daffodil.apache.org to make a decision as a community if the timing is correct for a release and what open issues should be resolved for a release. Ensure there is at leas 72 hours for discussion before moving forward.
   
   
2. Upon agreement, someone should volunteer to be the "Release Manager" to take the responsibility to prepare the release candidate.

...

The following steps must only be performed once to setup signing keys and the file distribution SVN repository.

Apache Dist Repository

...

Signing Keys

Release files must be signed with an OpenPGP compatible key. If you do not already have a key for signing Apache releases, follow the developer instructions in the Daffodil KEYS file to generate a key and add it to the KEYS file. Follow the contributor workflow and create a review branch and pull request to commit your changes to the KEYS file. Once merged, perform the following steps:

• Clone the Apache Dist Daffodil release directory, copy the KEYS file, and commit it:

  
  

  Code Block
  language bash
  $ svn checkout https://dist.apache.org/repos/dist

...

• /release/incubator/daffodil/ daffodil-dist $

...

Staged files are created in the dev directory and are moved to the release directory once approved by the Apache Incubator Project Management Committee.

Daffodil Site Repository

The Daffodil release script modifies files in the Daffodil website repository, and you will need to make manual changes to the repsository as well. Clone the git repo with the following command:

$ git clone https://github.com/apache/incubator-daffodil-site

Signing Keys

Release files must be signed with an OpenPGP compatible key. If you do not already have a key for signing Apache releases, follow the developer instructions in the KEYS file in the Daffodil repository to generate a key and add it to the KEYS file. Follow the contributor workflow and create a review branch and pull request to commit your changes to the KEYS file. Once merged, perform the following steps:

...

$ gpg --fingerprint KEYID

...

$ gpg --send-keys KEYID

For more information on signing keys, visit How to OpenPGP and Signing Releases.

SBT PGP

The sbt-pgp plugin is required to publish signed releases. Add the following to the file ~/.sbt/1.0/plugins/pgp.sbt to enable usage of the plugin:

addSbtPlugin("com.jsuereth" % "sbt-pgp" % "1.1.1")

In most cases, no other configuration should be necessary.

WiX Toolset

The sbt-native-packager plugin is used by Daffodil to generate a Windows MSI installer. The plugin depends on WiX Toolset to do the actual MSI generation, which unfortunately only works on Windows. However, the release script must be run on Linux. Below are the steps necessary to configure a Linux system to use the WiX Toolset from the plugin using wine.

...

 Install wine and winetools for you system, for example on Fedora, run:

$ dnf install wine winetools

...

Install dotnet45 into wine using winetools

$ winetricks dotnet45

...

Extract that zip into a WIX specific directory:

$ mkdir ~/wix311/
$ unzip wix311-binaries.zip -d ~/wix311/

• cp daffodil.git/KEYS daffodil-dist $ cd daffodil-dist $ svn ci -m "Update Apache Daffodil KEYS"

    

• Add your key fingerprint to https://id.apache.org. To get your fingerprint, run the following:

  Code Block
  language bash
  $ gpg --fingerprint KEYID

  
  

• Send your key to a keyserver via the command:

  Code Block
  language bash
  $ gpg --send-keys KEYID

  
  

For more information on signing keys, visit How to OpenPGP and Signing Releases.

Creating a Release Candidate

1. Prior to creating the release candidate, the version setting in build.sbt should contain the -SNAPSHOT keyword. Create and merge a pull request to remove this keyword in preparation for a non-snapshot release.

     

2. To improve reproducibilty and to minimize the effects and variability of a users environment, release candidates should be created using the Daffodil release candidate container. Although the following commands use and have been tested with podman, you should be able to replace podman with docker if you would rather use docker. Install docker or podman using your systems package manager or from the containers website. For example:

   Code Block
   language bash
   $ sudo dnf install podman

      

3. Build the Daffodil release candidate image:

   Code Block
   language bash
   $ podman build -t daffodil-release-candidate /path/to/daffodil.git/containers/release-candidate/

     

4. Run the daffodil release candidate container:

   Code Block
   language bash
   $ podman run -it \ -v ~/.gitconfig:/root/.gitconfig \ -v ~/.gnupg/:/root/.gnupg/ \ -v ~/.ssh/:/root/.ssh/ \ daffodil-release-candidate

      

5. The container will periodically ask for user input (e.g. usenames, passwords) to sign and publish release files. This includes:
     

   1. Release candidate label. For example: rc1 if this is the first release candidate for a version
        
   2. Long format of your signing key ID. This can be found by running gpg --list-secret-keys --keyid-format long 
        
   3. Git commit name and email. This is the name and email you want to show up as the "Comitter" when creating a git tag.
       
   4. Apache user name and password. This is the username and password credentials used to log in at https://id.apache.org.
       
   5. GitHub SSH key password. The Daffodil repository will be cloned using SSH authentication. If you SSH key is password protected, you may be prompted for that password.
        
   6. Private GPG password. The release process will sign artifacts with your GPG key–you will be prompted for a password to sign this artifacts.
        

6. After entering the necessary information, this script will perform the following actions:
   
   

   1. Create a zip of the source
      
      
   2. Create tgz, zip, msi, and rpm of the helper binary
      
      
   3. Create sha256 and sha512 checksum and ASCII armored detached signatures of the above files
      
      
   4. Move the above files to the Apache dist dev directory
      
      
   5. Create javadoc and scaladoc and move to the daffodil site repository docs directory for this release
      
      
   6. Stages jars/poms to https://repository.apache.org
      
      
   7. Create a signed git tag
      
      
7. Once the script completes, you should verify all the files. The script will list the files and locations to verify. This includes:
   
   
   1. Verify the checksums and signatures created in the Apache dist directories are correct
      
      
   2. Verify the staged jars/poms at https://repository.apache.org/ are correct. To do so, visit that url, login in the top right using id.apache.org credentials, select "Staging Repositories" on the left, and find the orgapachedaffodil-XXXX repository. Inspect the "Content" tab to make sure the appropriate jars are uploaded and appear valid.
      
      
   3. Verify the git tag is correct
      
      
   4. Verify the javadoc and scala docs in the daffodil site repository are correct
     
8. If any of the above do not look correct perform the following steps:
     
   1. Drop the published jars/poms (at https://repository.apache.org - check the box for the staging repository just created and choose "Drop" at the top)
       
   2. Type exit  to close the container. All files created in the container will be deleted.
       
   3. Fix the issue and repeat the "Create Release Candidate" process from the beginning.
        
9. After verifying all is correct, run the commands provided at the end of the script to perform the following:
      
   1. Commit the release artifacts
        
   2. Push the new tag
        
   3. Update the daffodil site repository
        
   4. Close the staged files in the Apache repsitory
        
10. You are now done with the container. Type exit  to close it.

...

Run the following command to set the WIX environment variable to that directory. It is reccommended that this also be added to ~/.bashrc:

$ export WIX=~/wix311/

Add symbolic links to the the WIX directory that point to a custom script in the Daffodil repository:

$ ln -s ~/incubator-daffodil/scripts/wix_wine.sh $WIX/\\bin\\candle.exe
$ ln -s ~/incubator-daffodil/scripts/wix_wine.sh $WIX/\\bin\\light.exe

Note that the bin, double-slashes, and .exe are necessary, as they work around assumptions made the the plugin about running on a Windows environment. 

Creating a Release Candidate

1. Prior to creating the release candidate, the version setting in build.sbt should contain the -SNAPSHOT keyword. Create and merge a pull request to remove this keyword in preparation for a non-snapshot release.

      .

2. From within the root of the Daffodil directory, execute the scripts/release-candidate.sh script, providing the release candidate label (e.g. rc1), the path to the root of apache-dist directory created above, that path the the root of the daffodil site repository, your Apache login credentials (e.g. for https://id.apache.org), and your long format gpg key id (e.g. gpg --list-keys --keyid-format long KEYID). Run the script like so:
   

   Code Block
   language bash
   $ ./scripts/release-candidate.sh

   The credentials are used to publish the jars to the Apache staging repo. You will also be asked to enter the password for your private gpg key created above to sign the published jars and the zip/tars . This script will perform the following actions:
   Create a zip of the source
   Create tgz, zip, msi, and rpm of the helper binary
   Create sha256 and sha512 checksum and ASCII armored detached signatures of the above files
   Move the above files to the Apache dist dev directory
   Create javadoc and scaladoc and move to the daffodil site repository docs directory for this release
   Stages jars/poms to https://repository.apache.org
   Create a signed git tag
   Once the script completes, you should verify all the files. This includes:
   Verify the checksums and signatures created in the Apache dist directories are correct
   Verify the staged jars/poms at https://repository.apache.org/ are correct. To do so, visit that url, login in the top right using id.apache.org credentials, select "Staging Repositories" on the left, and find the orgapachedaffodil-XXXX repository. Inspect the "Content" tab to make sure the appropriate jars are uploaded and appear valid.
   Verify the git tag is correct
   
3. Verify the javadoc and scala docs in the daffodil site repository are correct
If any of the above do not look correct you will need to rerun the release candidate script; however,  before doing so you must
 

4. Delete the files in the Apache dist directory
    
5. Drop the published jars/poms (at https://repository.apache.org - check the box for the staging repository just created and choose "Drop" at the top)
    
6. Delete the git tag (git tag -d tagname).
     
7. Delete the files in the daffodil site repository
    
Fix whatever the issue is and repeat from step 2.
After verifying all is correct, commit the changes:


Commit the files in Apache dist, for example:

Code Block
language bash
svn add dev/incubator/daffodil/* svn ci -m "Stage Apache Daffodil (incubating) 2.0.0-rc1"

Close the published Nexus files by visiting https://repository.apache.org, log in, find the release in "Staging Repositories" and select "Close".


Push the git tag

Code Block

language	bash

git push asf v2.0.0-rc1

Update the Website

Create a new release file in the site/_releases/ directory in the Daffodil Site Repository, updating the page to include a summary of the changes and links/descriptions of the bugs that were fixed in this release. Parameters that must be set because this is a release candidate include:

...

Follow the steps in the README in that repository to test and publish the new release page.

...

If the VOTE does not pass, "Drop" the release at https://repository.apache.org, and delete the dist files, e.g.:

$ svn delete -m "Drop Apache Daffodil (incubating) 2.0.0-rc1" \
    https://dist.apache.org/repos/dist/svn rm dev/incubator/daffodil/*
svn ci -m "Drop Apache Daffodil (incubating) 2.0.0-rc1"/

Once the issues are resolved, start again at Creating a Release Candidate to create a new release candidate with a bumped rc number (e.g. rc2).

...

1. In the Apache dist directory, move the release candidate files to the release directory:

   Code Block
   language bash
   svn mv $ svn mv -m "Release Apache Daffodil (incubating) 2.0.0" \ https://dist.apache.org/repos/dist/dev/incubator/daffodil/2.0.0-rc1/ \ https://dist.apache.org/repos/dist/release/incubator/daffodil/2.0.0/ svn ci -m "Release Apache Daffodil (incubating) 2.0.0"

   
   

2. In the Daffodil git repository, create a signed git tag based on the release candidate tag

   Code Block
   language bash
   $ git tag -as -u KEYID -m "Release v2.0.0" rel/v2.0.0 v2.0.0-rc1 $ git push asf rel/v2.0.0

   
   

3. Release the published Nexus files by visiting https://repository.apache.org, log in, find the release in "Staging Repositories" and selecting "Release".
   
   

4. Give approximately 24 hours for the release files to sync to mirrors and maven central.
    

5.  Once the mirrors have synced, make the following changes to the daffodil site repository to make the release available:

     

   1. Modify the release page to have the following parameters:

      Code Block
      released: true date: date of release artifact-root: "https://www.apache.org/dyn/closer.lua/incubator/daffodil/2.0.0/" checksum-root: "https://www.apache.org/dist/incubator/daffodil/2.0.0/"

      
      

   2. Modify the release page of the previous release to use archived root URLs, for example:

      Code Block
      artifact-root: "https://archive.apache.org/dist/incubator/daffodil/1.0.0/" checksum-root: "https://archive.apache.org/dist/incubator/daffodil/1.0.0/"

      
      

   3. Modify the doap.rdf file to include the release date and version, for example:

      Code Block
      language xml
      <release> <Version> <name>Apache Daffodil</name> <created>2018-02-18</created> <revision>2.0.0</revision> </Version> </release>

      
      

   4. Update the symlink to the latest Javadoc and Scaladocs

      Code Block
      language bash
      $ ln -sfn 2.0.0 site/docs/latest

      
      

   5. Remove the previous release from the Apache dist repository now that the download URLs point to the archives:

      Code Block
      language bash
      $ svn deletesvn rm release/incubator/daffodil/1.0.0/ svn ci -m "Archive Apache Daffodil (incubating) 1.0.0" \ https://dist.apache.org/repos/dist/release/incubator/daffodil/1.0.0/

      
      

   6. Update the JIRA versions to mark the version as released.

...