发版准备

Apache 项目的版本发布必须严格遵循 Apache 基金会的版本发布流程。相关指导和政策可参阅：

本文档主要说明版本发布的主要流程和前期准备工作。具体 Doris 各组件的发版步骤，可以参阅各自的文档：

Apache 项目的版本发布主要有以下三种形式：

  • Source Release：即源码发布，这个是必选项。
  • Binary Release：即二进制发布，比如发布编译好的可执行程序。这个是可选项。
  • Convenience Binaries：为方便用户使用而发布到第三方平台的 Release。如Maven、Docker等。这个也是可选项。

发版流程

每个项目的发版都需要一位 PMC 成员或 Committer 作为 Release Manager。

总体的发版流程如下：

  1. 环境准备
  2. 发布准备
    1. 社区发起 DISCUSS 并与社区交流具体发布计划
    2. 创建分支用于发布
    3. 清理 issue
    4. 将必要的 Patch 合并到发布的分支
  3. 验证分支
    1. QA 稳定性测试
    2. 验证分支代码的编译流程
    3. 准备 Release Nodes
  4. 准备发布材料
    1. 打 Tag
    2. 将需要发布的内容上传至 Apache Dev SVN 仓库发版准备 - 图4 (opens new window)
    3. 其他 Convenience Binaries 的准备（如上传到 Maven Staging 仓库发版准备 - 图5 (opens new window)）
  5. 社区发布投票流程
    1. 在 Doris 社区 Dev 邮件组发起投票。
    2. 投票通过后，在 Doris 社区发 Result 邮件。
    3. 如果是孵化项目（Incuator Project）还需：
      1. 在 Incubator General 邮件组 发起投票。
      2. 发 Result 邮件到 general@incubator.apache.org。
  6. 完成工作
    1. 上传签名的软件包到 Apache Release 仓库发版准备 - 图6 (opens new window)，并生成相关链接。
    2. 在 Doris 官网和 github 发布下载链接，并且清理 svn 上的旧版本包。
    3. 发送 Announce 邮件到 dev@doris.apache.org
    4. 如果是孵化项目（Incuator Project）还需：
      1. 发送 Announce 邮件到 general@incubator.apache.org

准备签名

如果这是你第一次发布，那么你需要在你的环境中准备如下工具

  1. Release Signing发版准备 - 图7 (opens new window)
  2. gpg发版准备 - 图8 (opens new window)
  3. svn发版准备 - 图9 (opens new window)

准备gpg key

Release manager 在发布前需要先生成自己的签名公钥，并上传到公钥服务器，之后就可以用这个公钥对准备发布的软件包进行签名。 如果在KEY发版准备 - 图10 (opens new window)里已经存在了你的KEY，那么你可以跳过这个步骤了。

签名软件 GnuPG 的安装配置

GnuPG

1991年，程序员 Phil Zimmermann 为了避开政府监视，开发了加密软件PGP。这个软件非常好用，迅速流传开来，成了许多程序员的必备工具。但是，它是商业软件，不能自由使用。所以，自由软件基金会决定，开发一个PGP的替代品，取名为GnuPG。这就是GPG的由来。

安装配置

CentOS 安装命令：

  1. yum install gnupg

安装完成后，默认配置文件 gpg.conf 会放在 home 目录下。

  1. ~/.gnupg/gpg.conf

如果不存在这个目录或文件，可以直接创建一个空文件。

Apache 签名推荐 SHA512， 可以通过配置 gpg 完成。 编辑gpg.conf, 增加下面的三行：

  1. personal-digest-preferences SHA512
  2. cert-digest-algo SHA512
  3. default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed

生成新的签名

准备签名

推荐的生成新签名的设置：

这里必须通过 SecureCRT 等终端直接登录用户账户，不能通过 su - user 或者 ssh 转，否则密码输入 box 会显示不出来而报错。

先看下 gpg 的 version 以及是否支持 SHA512.

  1. $ gpg --version
  2. gpg (GnuPG) 2.0.22
  3. libgcrypt 1.5.3
  4. Copyright (C) 2013 Free Software Foundation, Inc.
  5. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
  6. This is free software: you are free to change and redistribute it.
  7. There is NO WARRANTY, to the extent permitted by law.
  9. Home: ~/.gnupg
  10. Supported algorithms:
  11. Pubkey: RSA, ?, ?, ELG, DSA
  12. Cipher: IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH,
  13.         CAMELLIA128, CAMELLIA192, CAMELLIA256
  14. Hash: MD5, SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
  15. Compression: Uncompressed, ZIP, ZLIB, BZIP2
生成新的签名
  1. $ gpg --gen-key
  2. gpg (GnuPG) 2.0.22; Copyright (C) 2013 Free Software Foundation, Inc.
  3. This is free software: you are free to change and redistribute it.
  4. There is NO WARRANTY, to the extent permitted by law.
  6. Please select what kind of key you want:
  7.    (1) RSA and RSA (default)
  8.    (2) DSA and Elgamal
  9.    (3) DSA (sign only)
  10.    (4) RSA (sign only)
  11. Your selection? 1
  12. RSA keys may be between 1024 and 4096 bits long.
  13. What keysize do you want? (2048) 4096
  14. Requested keysize is 4096 bits
  15. Please specify how long the key should be valid.
  16.          0 = key does not expire
  17.       <n>  = key expires in n days
  18.       <n>w = key expires in n weeks
  19.       <n>m = key expires in n months
  20.       <n>y = key expires in n years
  21. Key is valid for? (0)
  22. Key does not expire at all
  23. Is this correct? (y/N) y
  25. GnuPG needs to construct a user ID to identify your key.
  27. Real name: xxx
  28. Name must be at least 5 characters long
  29. Real name: xxx-yyy
  30. Email address: xxx@apache.org
  31. Comment: xxx's key
  32. You selected this USER-ID:
  33.     "xxx-yyy (xxx's key) <xxx@apache.org>"
  35. Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o

其中 Real name 需保持和 id.apache.org 中显示的 id 一致。 Email address 为 apache 的邮箱。

输入 passphrase, 一共要输入两遍，超过8个字符即可。

这里的秘钥一定要记住，后面签名的时候会用到。同时也会用于其他组件的发布

查看和输出

第一行显示公钥文件名（pubring.gpg），第二行显示公钥特征（4096位，Hash字符串和生成时间），第三行显示”用户ID”，注释，邮件，第四行显示私钥特征。

  1. $ gpg --list-keys
  2. /home/lide/.gnupg/pubring.gpg
  3. -----------------------------
  4. pub   4096R/33DBF2E0 2018-12-06
  5. uid                  xxx-yyy  (xxx's key) <xxx@apache.org>
  6. sub   4096R/0E8182E6 2018-12-06

其中 xxx-yyy 就是用户ID。

  1. gpg --armor --output public-key.txt --export [用户ID]
  1. $ gpg --armor --output public-key.txt --export xxx-yyy
  2. 文件‘public-key.txt’已存在。 是否覆盖？(y/N)y
  3. $ cat public-key.txt
  4. -----BEGIN PGP PUBLIC KEY BLOCK-----
  5. Version: GnuPG v2.0.22 (GNU/Linux)
  7. mQINBFwJEQ0BEACwqLluHfjBqD/RWZ4uoYxNYHlIzZvbvxAlwS2mn53BirLIU/G3
  8. 9opMWNplvmK+3+gNlRlFpiZ7EvHsF/YJOAP59HmI2Z...

上传签名公钥

公钥服务器是网络上专门储存用户公钥的服务器。send-keys 参数可以将公钥上传到服务器。

  1. gpg --send-keys xxxx --keyserver https://keyserver.ubuntu.com/

其中 xxxx 为上一步 --list-keys 结果中 pub 后面的字符串，如上为：33DBF2E0

也可以通过https://keyserver.ubuntu.com/发版准备 - 图11 (opens new window)上传上述 public-key.txt 的内容：

上传成功之后，可以通过查询这个https://keyserver.ubuntu.com/发版准备 - 图12 (opens new window)，输入 0x33DBF2E0 查询。（注意需要以 0x 开头）

该网站查询有延迟，可能需要等1个小时。

生成 fingerprint 并上传到 apache 用户信息中

由于公钥服务器没有检查机制，任何人都可以用你的名义上传公钥，所以没有办法保证服务器上的公钥的可靠性。通常，你可以在网站上公布一个公钥指纹，让其他人核对下载到的公钥是否为真。

fingerprint参数生成公钥指纹：

  1. gpg --fingerprint [用户ID]
  1. $ gpg --fingerprint xxx-yyy
  2. pub   4096R/33DBF2E0 2018-12-06
  3.       Key fingerprint = 07AA E690 B01D 1A4B 469B  0BEF 5E29 CE39 33DB F2E0
  4. uid                  xxx-yyy (xxx's key) <xxx@apache.org>
  5. sub   4096R/0E8182E6 2018-12-06

将上面的 fingerprint （即 07AA E690 B01D 1A4B 469B 0BEF 5E29 CE39 33DB F2E0）粘贴到自己的用户信息中：

https://id.apache.org

OpenPGP Public Key Primary Fingerprint:

注：每个人可以有多个 Public Key。

生成 keys

注意不要删除 KEYS 文件中已有的内容，这能追加新增

  1. svn co https://dist.apache.org/repos/dist/dev/incubator/doris/
  2. # edit doris/KEYS file
  3. gpg --list-sigs [用户 ID] >> doris/KEYS
  4. gpg --armor --export [用户 ID] >> doris/KEYS
  5. svn ci --username $ASF_USERNAME --password "$ASF_PASSWORD" -m"Update KEYS"

注意，KEYS 文件要同时发布到如下 svn 库。

  1. svn co https://dist.apache.org/repos/dist/release/incubator/doris
  2. # edit doris/KEYS file
  3. svn ci --username $ASF_USERNAME --password "$ASF_PASSWORD" -m"Update KEYS"

之后会自动同步到：

  1. https://downloads.apache.org/incubator/doris/KEYS

在后续的发版投票邮件中，要使用 https://downloads.apache.org/incubator/doris/KEYS 这里的 KEYS 文件。

Maven 发版准备

对于 Doris Connector 等组件，需要使用 maven 进行版本发布。

  1. 生成主密码

    mvn --encrypt-master-password <password>

    这个密码仅用作加密后续的其他密码使用, 输出类似 {VSb+6+76djkH/43...}

    之后创建 ~/.m2/settings-security.xml 文件，内容是

    1. <settingsSecurity>
    2.   <master>{VSb+6+76djkH/43...}</master>
    3. </settingsSecurity>

  2. 加密 apache 密码

    mvn --encrypt-password <password>

    这个密码是apache 账号的密码 输出和上面类似{GRKbCylpwysHfV...}

    在 ~/.m2/settings.xml 中加入

    1. <servers>
    2.   <!-- To publish a snapshot of your project -->
    3.   <server>
    4.     <id>apache.snapshots.https</id>
    5.     <username>yangzhg</username>
    6.     <password>{GRKbCylpwysHfV...}</password>
    7.   </server>
    8.   <!-- To stage a release of your project -->
    9.   <server>
    10.     <id>apache.releases.https</id>
    11.     <username>yangzhg</username>
    12.     <password>{GRKbCylpwysHfV...}</password>
    13.   </server>
    14. </servers>

在社区发起 DISCUSS

DISCUSS 并不是发版前的必须流程，但强烈建议在重要版本发布前，在 dev@doris 邮件组发起讨论。内容包括但不限于重要功能的说明、Bug修复说明等。