dev-support/create-release/README.txt

   1 Creates an HBase release candidate.
   2
   3 The scripts in this directory came originally from spark
   4 (https://github.com/apache/spark/tree/master/dev/create-release). They were
   5 then modified to suit the hbase context. These scripts supercede the old
   6 _../make_rc.sh_ script for making release candidates because what is here is
   7 more comprehensive doing more steps of the RM process as well as running in a
   8 container so the RM build environment can be a constant.
   9
  10 It:
  11
  12  * Tags release
  13  * Sets version to the release version
  14  * Sets version to next SNAPSHOT version.
  15  * Builds, signs, and hashes all artifacts.
  16  * Pushes release tgzs to the dev dir in a apache dist.
  17  * Pushes to repository.apache.org staging.
  18
  19 The entry point is the do-release-docker.sh script. It requires a local
  20 docker; for example, on mac os x, a Docker for Desktop installed and running.
  21
  22 (To run a build w/o invoking docker (not recommended!), use _do_release.sh_.)
  23
  24 The scripts will query interactively for needed parameters and passphrases.
  25 For explanation of the parameters, execute:
  26
  27  $ release-build.sh --help
  28
  29 The scripts run in dry-run mode by default where only local builds are
  30 performed and nothing is uploaded to the ASF repos. Pass the '-f' flag
  31 to remove dry-run mode.
  32
  33 Before starting the RC build, run a reconciliation of what is in JIRA with
  34 what is in the commit log. Make sure they align and that anomalies are
  35 explained up in JIRA. See http://hbase.apache.org/book.html#maven.release
  36 for how.
  37
  38 Regardless of where your release build will run (locally, locally in docker,
  39 on a remote machine, etc) you will need a local gpg-agent with access to your
  40 secret keys. Before starting an RC build, make sure your local gpg-agent has
  41 configs to properly handle your credentials, especially if you want to avoid
  42 typing the passphrase to your secret key: e.g. if you are going to run
  43 and step away (the RC creation takes ~5 hours), best to increase the TTL on
  44 caching the unlocked secret by setting the following into local your
  45 ~/.gnupg/gpg-agent.conf file:
  46   # in seconds, e.g. a day
  47   default-cache-ttl 86400
  48   max-cache-ttl 86400
  49
  50 A quick way to tell gpg to clear out state, re-read the gpg-agent.conf file
  51 and start a new gpg-agent is via the following command phrase:
  52
  53  $ gpgconf --kill all && gpg-connect-agent /bye
  54
  55 You can verify options took hold with '$ gpg --list-options gpg-agent'.
  56
  57 Similarly, run ssh-agent with your ssh key added if building with docker.
  58
  59 Running a build on GCE is easy enough. Here are some notes if of use.
  60 Create an instance. 4CPU/15G/20G disk seems to work well enough.
  61 Once up, run the below to make your machine fit for RC building:
  62
  63 # Presuming debian-compatible OS, do these steps on the VM.
  64 # Your VM username should be your ASF id, because it will show up in build artifacts.
  65 # Follow the docker install guide: https://docs.docker.com/engine/install/debian/
  66 $ sudo apt-get install -y \
  67     apt-transport-https \
  68     ca-certificates \
  69     curl \
  70     gnupg2 \
  71     software-properties-common
  72 $ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
  73 $ sudo add-apt-repository -y \
  74    "deb [arch=amd64] https://download.docker.com/linux/debian \
  75    $(lsb_release -cs) \
  76    stable"
  77 $ sudo apt-get update
  78 $ sudo apt-get install -y docker-ce docker-ce-cli containerd.io
  79 # Follow the post installation steps: https://docs.docker.com/engine/install/linux-postinstall/
  80 $ sudo usermod -aG docker $USER
  81 # LOGOUT and then LOGIN again so $USERID shows as part of docker group
  82 # Test here by running docker's hello world as your build user
  83 $ docker run hello-world
  84
  85 # Follow the GPG guide for forwarding your gpg-agent from your local machine to the VM
  86 #   https://wiki.gnupg.org/AgentForwarding
  87 # On the VM find out the location of the gpg agent socket and extra socket
  88 $ gpgconf --list-dir agent-socket
  89 /run/user/1000/gnupg/S.gpg-agent
  90 $ gpgconf --list-dir agent-extra-socket
  91 /run/user/1000/gnupg/S.gpg-agent.extra
  92 # On the VM configure sshd to remove stale sockets
  93 $ sudo bash -c 'echo "StreamLocalBindUnlink yes" >> /etc/ssh/sshd_config'
  94 $ sudo systemctl restart ssh
  95 # logout of the VM
  96
  97 # Do these steps on your local machine.
  98 # make sure gpg-agent is running
  99 $ gpg-connect-agent /bye
 100 # Export your public key and copy it to the VM.
 101 # Assuming 'example.gce.host' maps to your VM's external IP (or use the IP)
 102 $ gpg --export example@apache.org > ~/gpg.example.apache.pub
 103 $ scp ~/gpg.example.apache.pub example.gce.host:
 104 # ssh into the VM while forwarding the remote gpg socket locations found above to your local
 105 #   gpg-agent's extra socket (this will restrict what commands the remote node is allowed to have
 106 #   your agent handle. Note that the gpg guide above can help you set this up in your ssh config
 107 #   rather than typing it in ssh like this every time.
 108 $ ssh -i ~/.ssh/my_id \
 109     -R "/run/user/1000/gnupg/S.gpg-agent:$(gpgconf --list-dir agent-extra-socket)" \
 110     -R "/run/user/1000/gnupg/S.gpg-agent.extra:$(gpgconf --list-dir agent-extra-socket)" \
 111     example.gce.host
 112
 113 # now in an SSH session on the VM with the socket forwarding
 114 # import your public key and test signing with the forwarding to your local agent.
 115 $ gpg --no-autostart --import gpg.example.apache.pub
 116 $ echo "foo" > foo.txt
 117 $ gpg --no-autostart --detach --armor --sign foo.txt
 118 $ gpg --no-autostart --verify foo.txt.asc
 119
 120 # install git and clone the main project on the build machine
 121 $ sudo apt-get install -y git
 122 $ git clone https://github.com/apache/hbase.git
 123 # finally set up an output folder and launch a dry run.
 124 $ mkdir ~/build
 125 $ cd hbase
 126 $ ./dev-support/create-release/do-release-docker.sh -d ~/build