.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
.. use this file except in compliance with the License. You may obtain a copy of
.. the License at
..
..   http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.. License for the specific language governing permissions and limitations under
.. the License.

How to release
==============

This guide explains how to prepare for a source and binary release of Apache Crail (Incubating) project for
a release number of ``x.y`` (indicated as ``${RELEASE_VERSION}``) and release candidate number ``X`` as ``rcX``
(indicated as ``${RELEASE_CANDIDATE}``).

.. contents:: Table of Contents


1. Configure your environment for a release
-------------------------------------------
Before we do a release, lets start by setting up the release environment (and cross check some of the other
settings).

1.1 Setup git username
^^^^^^^^^^^^^^^^^^^^^^

Make sure ``git`` is configured properly.

.. code-block:: bash

   git config user.email "your_id@apache.org"
   git config user.name "your_name"


1.2 Setup keys
^^^^^^^^^^^^^^

1. Generate a code signing key, https://www.apache.org/dev/openpgp.html#generate-key

.. code-block:: bash

   gpg --gen-key


2. Check the preference for SHA-1 for your key, https://www.apache.org/dev/openpgp.html#key-gen-avoid-sha1

.. code-block:: bash

   gpg --edit-key your_key_id


3. Upload/publish the key: https://www.apache.org/dev/release-signing.html#keyserver-upload

.. code-block:: bash

   gpg --keyserver pgp.mit.edu --send-keys <key id>

4. Add your KEY in the KEYS file:

.. code-block:: bash

   svn co https://dist.apache.org/repos/dist/release/incubator/crail/
   cd crail
   (gpg --list-sigs <key id> && gpg --armor --export <key id>) >> KEYS
   svn commit KEYS -m "your_name (id@apache.org) keys"


6. Update your profile https://id.apache.org/ with the fingerprint of the key. Find your fingerprint at

.. code-block:: bash

   gpg --fingerprint


1.3 Maven Settings File
^^^^^^^^^^^^^^^^^^^^^^^
Prior to performing an Apache Crail release, you must have an entry such as this in your ~/.m2/settings.xml file to authenticate when deploying the release artifacts.

.. code-block:: xml

   <?xml version="1.0" encoding="UTF-8"?>
   <settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"
       xmlns="http://maven.apache.org/SETTINGS/1.0.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     <servers>
       <server>
         <id>apache.snapshots.https</id>
         <username>USERNAME</username>
         <password>PASSWORD</password>
       </server>
       <server>
         <id>apache.releases.https</id>
         <username>USERNAME</username>
         <password>PASSWORD</password>
       </server>
     </servers>
  </settings>


How to put encrypted password https://maven.apache.org/guides/mini/guide-encryption.html

2. Preparing for a release
--------------------------

A release consists of a doing a (i) source release; (b) binary release; (iii) uploading maven artifacts; (iv) updating documentation. To do a version release of ``x.y`` (which is referred to as ``${RELEASE_VERSION}``), follow these steps:


1. Go through the closed JIRAs and merge requests, and update the HISTORY.md file about what is new in the new release version.


2. Perform ``mvn apache-rat:check`` and make sure it is a SUCCESS.


3. Perform ``mvn checkstyle:check``. For now it will fail, but make sure that it runs. We need to gradually fix it. [JIRA-59](https://issues.apache.org/jira/browse/CRAIL-59)

4. Perform maven prepare release in the interactive mode.


.. code-block:: bash

   mvn release:prepare -P apache-release -Darguments="-DskipTests"  -DinteractiveMode=true -Dresume=false


The interactive mode allows us to explicitly name the current release version, release candidate, and next version. The convention here is to follow ``apache-crail-${RELEASE_VERSION}-incubating-${RELEASE_CANDIDATE}`` naming, starting from release candidate 0. So, for a ${RELEASE_VERSION} of 2.12 and release candidate 10, the name would be ``apache-crail-2.12-incubating-rc10``. For ``rc0``, we let the command increment the pom version. Here is an example run of this command for the release for ``1.2-incubating``. As you can see, the first time you run the command (for ``rc0``, the version are picked automatically). For subsequent RCs, you have to make sure that version is not incremented unless a RC is successfully voted on. Between RCs, we expect everything to remain the same except the ``SCM release tag`` that you must keep in sync with the release candidate.

**NOTE:** the SCM tag does not have ``incubating`` in its name, and uses a ``v`` prefix.

.. code-block:: bash

   [INFO] Checking dependencies and plugins for snapshots ...
   What is the release version for "Crail Project Parent POM"? (org.apache.crail:crail-parent) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail Client Project"? (org.apache.crail:crail-client) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail RPC Project"? (org.apache.crail:crail-rpc) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail Namenode Project"? (org.apache.crail:crail-namenode) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail Storage Project"? (org.apache.crail:crail-storage) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail RDMA Project"? (org.apache.crail:crail-storage-rdma) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail NVMf Project"? (org.apache.crail:crail-storage-nvmf) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail Storage NaRPC Project"? (org.apache.crail:crail-storage-narpc) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail DaRPC Project"? (org.apache.crail:crail-rpc-darpc) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail RPC/TCP Project"? (org.apache.crail:crail-rpc-narpc) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail HDFS Project"? (org.apache.crail:crail-hdfs) 1.2-incubating: : 1.2-incubating
   What is the release version for "Crail Project Assembly"? (org.apache.crail:crail-assembly) 1.2-incubating: : 1.2-incubating
   What is SCM release tag or label for "Crail Project Parent POM"? (org.apache.crail:crail-parent) crail-parent-1.2-incubating: : v1.2-rc0
   What is the new development version for "Crail Project Parent POM"? (org.apache.crail:crail-parent) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail Client Project"? (org.apache.crail:crail-client) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail RPC Project"? (org.apache.crail:crail-rpc) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail Namenode Project"? (org.apache.crail:crail-namenode) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail Storage Project"? (org.apache.crail:crail-storage) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail RDMA Project"? (org.apache.crail:crail-storage-rdma) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail NVMf Project"? (org.apache.crail:crail-storage-nvmf) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail Storage NaRPC Project"? (org.apache.crail:crail-storage-narpc) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail DaRPC Project"? (org.apache.crail:crail-rpc-darpc) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail RPC/TCP Project"? (org.apache.crail:crail-rpc-narpc) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail HDFS Project"? (org.apache.crail:crail-hdfs) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   What is the new development version for "Crail Project Assembly"? (org.apache.crail:crail-assembly) 1.3-incubating-SNAPSHOT: : 1.3-incubating-SNAPSHOT
   [INFO] Transforming 'Crail Project Parent POM'...
   [...]


In case, if you are not sure about some setting, try `-DdryRun=true`.  If something goes wrong then ``mvn release:rollback``.


**NOTE:** the binary file and associated signature (asc) and sha512 files are generated
at ``assembly/target/crail-${RELEASE_VERSION}-incubating-bin.tar.gz``.  The source file and associated signature (asc) and sha512 files are
at ``assembly/target/crail-${RELEASE_VERSION}-incubating-src.tar.gz``.

5. We need to upload the generated artifacts to the "Stage" SVN at https://dist.apache.org/repos/dist/dev/incubator/crail/. So lets prepare that in a SVN staging directory (SSD)

.. code-block:: bash

   svn co https://dist.apache.org/repos/dist/dev/incubator/crail/
   cd crail
   mkdir ${RELEASE_VERSION}-${RELEASE_CANDIDATE}
   # lets call the created directory the svn staging directory (SSD)
   SSD=`pwd`/${RELEASE_VERSION}-${RELEASE_CANDIDATE}


6. Now we need to rename the artifacts to follow the naming convention. We collect all releasable artifact in the SVN staging directory (SSD)

.. code-block:: bash

   # copy files from the crail build location to the SVN staging directory (SSD)
   # binary file
   cp assembly/target/apache-crail-${RELEASE_VERSION}-incubating-bin.tar.gz ${SSD}/
   # source file
   cp assembly/target/apache-crail-${RELEASE_VERSION}-incubating-src.tar.gz ${SSD}/
   # copy signature files
   cp assembly/target/apache-crail-${RELEASE_VERSION}-incubating-bin.tar.gz.asc ${SSD}/
   cp assembly/target/apache-crail-${RELEASE_VERSION}-incubating-src.tar.gz.asc ${SSD}/
   # copy checksum files
   cp assembly/target/apache-crail-${RELEASE_VERSION}-incubating-bin.tar.gz.sha512 ${SSD}/
   cp assembly/target/apache-crail-${RELEASE_VERSION}-incubating-src.tar.gz.sha512 ${SSD}/
   # step in the SVN staging directory
   cd ${SSD}

7. Verify the checksums for source and binary files

.. code-block:: bash

  sha512sum -c apache-crail-${RELEASE_VERSION}-incubating-src.tar.gz.sha512
  sha512sum -c apache-crail-${RELEASE_VERSION}-incubating-bin.tar.gz.sha512


8. Verify the signatures for source and binary files

.. code-block:: bash

   gpg --verify apache-crail-${RELEASE_VERSION}-incubating-src.tar.gz.asc apache-crail-${RELEASE_VERSION}-incubating-src.tar.gz
   gpg --verify apache-crail-${RELEASE_VERSION}-incubating-bin.tar.gz.asc apache-crail-${RELEASE_VERSION}-incubating-bin.tar.gz


9. Commit the files after verification in the SVN staging directory

.. code-block:: bash

   svn add ${RELEASE_VERSION}-${RELEASE_CANDIDATE}
   svn commit ${RELEASE_VERSION}-${RELEASE_CANDIDATE} -m "${RELEASE_VERSION}-${RELEASE_CANDIDATE} release files"


10. Upload the artifacts to the Nexus https://repository.apache.org/index.html#welcome (login using your Apache ID) by calling

.. code-block:: bash

   mvn release:perform -P apache-release  -Darguments="-DskipTests"

11. After upload you need to

    1. Close the staging repository at https://repository.apache.org

    2. Login to https://repository.apache.org.

    3. Go to “Staging Repos”.

    4. Find the “orgapachecrail” repo with the Crail release. Be sure to expand the contents of the repo to confirm that it contains the correct Crail artifacts.

    5. Click on the “Close” button at top, and enter a brief description, such as “Apache Crail (Incubating) ${RELEASE_VERSION} release”.

    6. Copy the staging URL like ``https://repository.apache.org/content/repositories/orgapachecrail-1000/``


12. [Optionally] Check if docker images have been created successfully https://hub.docker.com/r/apache/incubator-crail/ and
https://hub.docker.com/r/apache/incubator-crail-rdma/. Make sure that the docker configuration file at
https://github.com/apache/incubator-crail/blob/v${RELEASE_VERSION}-${RELEASE_CANDIDATE}/docker/RDMA/Dockerfile contains the right
tag version for ``FROM crail:[RELEASE_TAG]`` and the right DiSNI version (which matches the pom file for this release)
at ``ARG DISNI_COMMIT="[DISNI_VERSION_FROM_CRAIL_POM]"``.


3. Voting on an RC
------------------

The voting is a 2 step process.

3.1 PPMC voting
^^^^^^^^^^^^^^^
First, we need to gather 3 binding votes (PPMC members) on the crail mailing list. To call the vote, you can use this template::


  Subject: [VOTE] Release of Apache Crail-${RELEASE_VERSION}-incubating [${RELEASE_CANDIDATE}]
  ============================================================================

  Hi all,

  This is a call for a vote on releasing Apache Crail ${RELEASE_VERSION}-incubating, release candidate X.

  The source and binary tarball, including signatures, digests, etc. can be found at:
  https://dist.apache.org/repos/dist/dev/incubator/crail/${RELEASE_VERSION}-incubating-${RELEASE_CANDIDATE}/

  The commit to be voted upon:
  https://git-wip-us.apache.org/repos/asf?p=incubator-crail.git;a=commit;h=[REF]

  The Nexus Staging URL:
  https://repository.apache.org/content/repositories/orgapachecrail-[STAGE_ID]

  Release artifacts are signed with the following key:
  https://www.apache.org/dist/incubator/crail/KEYS

  For information about the contents of this release, see:
  https://git-wip-us.apache.org/repos/asf?p=incubator-crail.git;a=blob;f=HISTORY.md;h=${RELEASE_HASH}
  or https://github.com/apache/incubator-crail/blob/v${RELEASE_VERSION}-${RELEASE_CANDIDATE}/HISTORY.md

  Please vote on releasing this package as Apache Crail ${RELEASE_VERSION}-incubating

  The vote will be open for 72 hours.

  [ ] +1 Release this package as Apache Crail ${RELEASE_VERSION}-incubating
  [ ] +0 no opinion
  [ ] -1 Do not release this package because ...


  Thanks,
  [YOUR_NAME]


Make sure that you modify (i) ${RELEASE_VERSION} in the subject and body; (ii) ${RELEASE_CANDIDATE} tags; (iii) ${RELEASE_HASH}; (iv) [STAGE_ID]; (iv) YOUR_NAME

After a successful vote, announce the result on the Crail mailing list::

  Subject: [RESULT][VOTE] Crail v${RELEASE_VERSION}-${RELEASE_CANDIDATE} release
  ==============================================

  Hi all,

  Thanks for all who voted. I'm closing the vote since the 72 hours have passed. Here are the results:
  X + votes
  Y - votes

  I will call for the IPMC vote.

  Thanks,
  [YOUR_NAME]


3.2 IPMC voting
^^^^^^^^^^^^^^^
After a succesfull PPMC vote, we need to call for the IPMC vote on the ``general@incubator.apache.org`` (https://incubator.apache.org/guides/lists.html). You can use this template::

  Subject:[VOTE] Apache Crail ${RELEASE_VERSION}-incubating (${RELEASE_CANDIDATE})
  ================================================

  Please vote to approve the source release of Apache Crail ${RELEASE_VERSION}-incubating (${RELEASE_CANDIDATE}).
  [If any] This release candidate fixes all issues raised in the last IPMC vote:
  - x
  - y
  - z

  The podling dev vote thread:

  https://www.mail-archive.com/dev@crail.apache.org/???.html

  The result:

  https://www.mail-archive.com/dev@crail.apache.org/???.html

  Commit hash: ${RELEASE_HASH}

  https://git1-us-west.apache.org/repos/asf?p=incubator-crail.git;a=commit;h=${RELEASE_HASH}

  Release files can be found at:
  https://dist.apache.org/repos/dist/dev/incubator/crail/${RELEASE_VERSION}-${RELEASE_CANDIDATE}/

  The Nexus Staging URL:
  https://repository.apache.org/content/repositories/orgapachecrail-[STAGE_ID]

  Release artifacts are signed with the following key:
  https://www.apache.org/dist/incubator/crail/KEYS

  For information about the contents of this release, see:
  https://git-wip-us.apache.org/repos/asf?p=incubator-crail.git;a=blob;f=HISTORY.md;h=${RELEASE_HASH}
  or https://github.com/apache/incubator-crail/blob/v${RELEASE_VERSION}-${RELEASE_CANDIDATE}/HISTORY.md

  The vote is open for at least 72 hours and passes if a majority of at least 3 +1 PMC votes are cast.

  [ ] +1 Release this package as Apache Crail 1.0-incubating
  [ ] -1 Do not release this package because ...

  Thanks,
  [YOUR_NAME]


After a successful vote, annouce the result as::

  Subject: [RESULT][VOTE] Apache Crail ${RELEASE_VERSION}-incubating (${RELEASE_CANDIDATE})
  =========================================================

  Hi all,

  Thanks for all your votes. Here is the result:
  x + votes
  y - votes

  [If any] Some comments for future votes that I'm about to address:
  - x
  - y
  - z

  I'm going to release Crail ${RELEASE_VERSION}-incubating. Thank you all for making this happen!

  Thanks,
  [YOUR_NAME]


Obviosuly not all calls to vote can succeed. In case of a failed vote, announce as::

  Subject:[CANCEL][VOTE] Release of Apache Crail ${RELEASE_VERSION}-incubating (${RELEASE_CANDIDATE})
  ===================================================================

  Hi all,
  I'm canceling the vote for Apache Crail ${RELEASE_VERSION}-incubating (${RELEASE_CANDIDATE}), due to found/discussed issues.

  I will prepare a new release candidate.

  Thanks,
  [YOUR_NAME]


**NOTE:** If your PPMC vote fails you have to redo the IPMC vote again after fixing the issues raised in the PPMC vote. 
 
4. After acceptance
-------------------

1. Tag the commit (on which the vote happened) with the release version without ``-${RELEASE_CANDIDATE}``. So, for example, after a successful vote on ``v1.2-rc5``, the hash will be tagged again with ``v1.2`` only.

2. Upload to the "release" (this is different from the "staging" SVN that we used before) SVN https://dist.apache.org/repos/dist/release/incubator

.. code-block:: bash

   svn co https://dist.apache.org/repos/dist/release/incubator
   cd incubator/crail
   mkdir ${RELEASE_VERSION}-incubating
   cd ${RELEASE_VERSION}-incubating
   # copy the tar.gz. asc. and sha512 files for the src and binary releases


3. Release nexus artifacts. Follow the step 12 in the release process but this time press the ``release`` button.

4. Write an announement email. You have to make announcement at two places, the general Apache announcement as well to crail mailing list.
You can use this template to make the announcement::

  Subject: [ANNOUNCE] Apache Crail ${RELEASE_VERSION}-incubating released
  ========================================================

  The Apache Crail community is pleased to announce the release of
  Apache Crail version ${RELEASE_VERSION}-incubating.

  [If any] The key features of this release are:
  - x
  - y
  - z

  Crail is a high-performance distributed data store designed for fast
  sharing of ephemeral data in distributed data processing workloads. You
  can read more about Crail on the website: https://crail.apache.org/

  The release is available at:
  https://crail.incubator.apache.org/download/

  The full change log is available here:
  https://github.com/apache/incubator-crail/blob/v${RELEASE_VERSION}/HISTORY.md

  We welcome any help and feedback. Check out https://crail.incubator.apache.org/community/
  to get involved.

  Thanks to all involved for making this first release happen!

  Thanks,
  [YOUR_NAME]

  --
  Apache Crail 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.```


The Apache annoucement list is at ``announce@apache.org``. You need to subscribe first.

5. Update the download page on the website

6. Social media (Twitter, LinkedIn announcements)

7. [Optionally] Check if docker images have been created successfully https://hub.docker.com/r/apache/incubator-crail/ and https://hub.docker.com/r/apache/incubator-crail-rdma/ with the new release tag.


5. Useful links
---------------
1. General info for release signing: https://www.apache.org/dev/release-signing.html
2. http://tephra.incubator.apache.org/ReleaseGuide.html
3. https://dubbo.incubator.apache.org/en-us/blog/prepare-an-apache-release.html