First, thank you for contributing to Iceberg Rust! The goal of this document is to provide everything you need to start contributing to iceberg-rust. The following TOC is sorted progressively, starting with the basics and expanding into more specifics.
We expect all community members to follow our Code of Conduct.
This document mainly introduces how the release manager releases a new version in accordance with the Apache requirements.
Source Release is the key point which Apache values, and is also necessary for an ASF release.
Source Release
Please remember that publishing software has legal consequences.
This guide complements the foundation-wide policies and guides:
In the context of our release, we use several terms to describe different stages of the release process.
Here's an explanation of these terms:
iceberg_version
0.2.0
release_version
0.2.0-rc.1
rc_version
rc.1
This section is the requirements for individuals who are new to the role of release manager.
Refer to Setup GPG Key to make sure the GPG key has been set up.
Start a tracking issue on GitHub for the upcoming release to track all tasks that need to be completed.
Title:
Tracking issues of Iceberg Rust ${iceberg_version} Release +
Content:
This issue is used to track tasks of the iceberg rust ${iceberg_version} release. + +## Tasks + +### Blockers + +> Blockers are the tasks that must be completed before the release. + +### Build Release + +#### GitHub Side + +- [ ] Bump version in project +- [ ] Update docs +- [ ] Generate dependencies list +- [ ] Push release candidate tag to GitHub + +#### ASF Side + +- [ ] Create an ASF Release +- [ ] Upload artifacts to the SVN dist repo + +### Voting + +- [ ] Start VOTE at iceberg community + +### Official Release + +- [ ] Push the release git tag +- [ ] Publish artifacts to SVN RELEASE branch +- [ ] Change Iceberg Rust Website download link +- [ ] Send the announcement + +For details of each step, please refer to: https://rust.iceberg.apache.org/release +
Bump all components' version in the project to the new iceberg version. +Please note that this version is the exact version of the release, not the release candidate version.
Cargo.toml
CHANGELOG.md
Download and setup cargo-deny. You can refer to cargo-deny.
cargo-deny
Running python3 ./scripts/dependencies.py generate to update the dependencies list of every package.
python3 ./scripts/dependencies.py generate
After bump version PR gets merged, we can create a GitHub release for the release candidate:
main
Bump Version
Patch up version
git tag -s "v0.2.0-rc.1"
git push --tags
If any step in the ASF Release process fails and requires code changes, +we will abandon that version and prepare for the next one. +Our release page will only display ASF releases instead of GitHub Releases.
After GitHub Release has been created, we can start to create ASF Release.
git checkout v0.2.0-rc.1
ICEBERG_VERSION=<iceberg_version> ICEBERG_VERSION_RC=<rc_version> ./scripts/release.sh
ICEBERG_VERSION=0.2.0 ICEBERG_VERSION_RC=rc.1 ./scripts/release.sh
release-${release_version}
dist
apache-iceberg-rust-${release_version}-src.tar.gz
apache-iceberg-rust-${release_version}-src.tar.gz.asc
apache-iceberg-rust-${release_version}-src.tar.gz.sha512
This script will create a new release under dist.
For example:
> tree dist +dist +├── apache-iceberg-rust-0.2.0-src.tar.gz +├── apache-iceberg-rust-0.2.0-src.tar.gz.asc +└── apache-iceberg-rust-0.2.0-src.tar.gz.sha512 +
SVN is required for this step.
The svn repository of the dev branch is: https://dist.apache.org/repos/dist/dev/iceberg/iceberg-rust
First, checkout Iceberg to local directory:
# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. +svn co https://dist.apache.org/repos/dist/dev/iceberg/iceberg-rust iceberg-dist-dev +
Then, upload the artifacts:
+The ${release_version} here should be like 0.2.0-rc.1 +
The ${release_version} here should be like 0.2.0-rc.1
${release_version}
cd iceberg-dist-dev +# create a directory named by version +mkdir ${release_version} +# copy source code and signature package to the versioned directory +cp ${repo_dir}/dist/* ${release_version}/ +# check svn status +svn status +# add to svn +svn add ${release_version} +# check svn status +svn status +# commit to SVN remote server +svn commit -m "Prepare for ${release_version}" +
Visit https://dist.apache.org/repos/dist/dev/iceberg/iceberg-rust/ to make sure the artifacts are uploaded correctly.
If you accidentally published wrong or unexpected artifacts, like wrong signature files, wrong sha256 files, +please cancel the release for the current release_version, +increase th RC counting and re-initiate a release with the new release_version. +And remember to delete the wrong artifacts from the SVN dist repo.
Iceberg Community Vote should send email to: dev@iceberg.apache.org:
[VOTE] Release Apache Iceberg Rust ${release_version} RC1 +
Hello, Apache Iceberg Rust Community, + +This is a call for a vote to release Apache Iceberg rust version ${iceberg_version}. + +The tag to be voted on is ${iceberg_version}. + +The release candidate: + +https://dist.apache.org/repos/dist/dev/iceberg/iceberg-rust/${release_version}/ + +Keys to verify the release candidate: + +https://downloads.apache.org/iceberg/KEYS + +Git tag for the release: + +https://github.com/apache/iceberg-rust/releases/tag/${release_version} + +Please download, verify, and test. + +The VOTE will be open for at least 72 hours and until the necessary +number of votes are reached. + +[ ] +1 approve +[ ] +0 no opinion +[ ] -1 disapprove with the reason + +To learn more about Apache Iceberg, please see https://rust.iceberg.apache.org/ + +Checklist for reference: + +[ ] Download links are valid. +[ ] Checksums and signatures. +[ ] LICENSE/NOTICE files exist +[ ] No unexpected binary files +[ ] All source files have ASF headers +[ ] Can compile from source + +More detailed checklist please refer to: +https://github.com/apache/iceberg-rust/tree/main/scripts + +To compile from source, please refer to: +https://github.com/apache/iceberg-rust/blob/main/CONTRIBUTING.md + +Here is a Python script in release to help you verify the release candidate: + +./scripts/verify.py + +Thanks + +${name} +
Example: https://lists.apache.org/thread/c211gqq2yl15jbxqk4rcnq1bdqltjm5l
After at least 3 +1 binding vote (from Iceberg PMC member), claim the vote result:
+1
[RESULT][VOTE] Release Apache Iceberg Rust ${release_version} RC1 +
Hello, Apache Iceberg Rust Community, + +The vote to release Apache Iceberg Rust ${release_version} has passed. + +The vote PASSED with 3 +1 binding and 1 +1 non-binding votes, no +0 or -1 votes: + +Binding votes: + +- xxx +- yyy +- zzz + +Non-Binding votes: + +- aaa + +Vote thread: ${vote_thread_url} + +Thanks + +${name} +
Example: https://lists.apache.org/thread/xk5myl10mztcfotn59oo59s4ckvojds6
# Checkout the tags that passed VOTE +git checkout ${release_version} +# Tag with the iceberg version +git tag -s ${iceberg_version} +# Push tags to github to trigger releases +git push origin ${iceberg_version} +
svn mv https://dist.apache.org/repos/dist/dev/iceberg/iceberg-rust/${release_version} https://dist.apache.org/repos/dist/release/iceberg/iceberg-rust/${iceberg_version} -m "Release ${iceberg_version}" +
Update the download link in website/src/download.md to the new release version.
website/src/download.md
Generate release notes
upgrade.md
Send the release announcement to dev@iceberg.apache.org and CC announce@apache.org.
dev@iceberg.apache.org
announce@apache.org
Instead of adding breaking changes, let's include the new features as "notable changes" in the announcement.
[ANNOUNCE] Release Apache Iceberg Rust ${iceberg_version} +
Hi all, + +The Apache Iceberg Rust community is pleased to announce +that Apache Iceberg Rust ${iceberg_version} has been released! + +Iceberg is a data access layer that allows users to easily and efficiently +retrieve data from various storage services in a unified way. + +The notable changes since ${iceberg_version} include: +1. xxxxx +2. yyyyyy +3. zzzzzz + +Please refer to the change log for the complete list of changes: +https://github.com/apache/iceberg-rust/releases/tag/v${iceberg_version} + +Apache Iceberg Rust website: https://rust.iceberg.apache.org/ + +Download Links: https://rust.iceberg.apache.org/download + +Iceberg Resources: +- Issue: https://github.com/apache/iceberg-rust/issues +- Mailing list: dev@iceberg.apache.org + +Thanks +On behalf of Apache Iceberg Community +
Example: https://lists.apache.org/thread/oy77n55brvk72tnlb2bjzfs9nz3cfd0s
+This section is a brief from the Cryptography with OpenPGP guideline. +
This section is a brief from the Cryptography with OpenPGP guideline.
For more details, please refer to GPG official website. Here shows one approach to install GPG with apt:
apt
sudo apt install gnupg2 +
Attentions:
Run gpg --full-gen-key and complete the generation interactively:
gpg --full-gen-key
gpg (GnuPG) 2.2.20; Copyright (C) 2020 Free Software Foundation, Inc. +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +Please select what kind of key you want: + (1) RSA and RSA (default) + (2) DSA and Elgamal + (3) DSA (sign only) + (4) RSA (sign only) + (14) Existing key from card +Your selection? 1 # input 1 +RSA keys may be between 1024 and 4096 bits long. +What keysize do you want? (2048) 4096 # input 4096 +Requested keysize is 4096 bits +Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + <n>w = key expires in n weeks + <n>m = key expires in n months + <n>y = key expires in n years +Key is valid for? (0) 0 # input 0 +Key does not expire at all +Is this correct? (y/N) y # input y + +GnuPG needs to construct a user ID to identify your key. + +Real name: Hulk Lin # input your name +Email address: hulk@apache.org # input your email +Comment: # input some annotations, optional +You selected this USER-ID: + "Hulk <hulk@apache.org>" + +Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O # input O +We need to generate a lot of random bytes. It is a good idea to perform +some other action (type on the keyboard, move the mouse, utilize the +disks) during the prime generation; this gives the random number +generator a better chance to gain enough entropy. +We need to generate a lot of random bytes. It is a good idea to perform +some other action (type on the keyboard, move the mouse, utilize the +disks) during the prime generation; this gives the random number +generator a better chance to gain enough entropy. + +# Input the security key +┌──────────────────────────────────────────────────────┐ +│ Please enter this passphrase │ +│ │ +│ Passphrase: _______________________________ │ +│ │ +│ <OK> <Cancel> │ +└──────────────────────────────────────────────────────┘ +# key generation will be done after your inputting the key with the following output +gpg: key E49B00F626B marked as ultimately trusted +gpg: revocation certificate stored as '/Users/hulk/.gnupg/openpgp-revocs.d/F77B887A4F25A9468C513E9AA3008E49B00F626B.rev' +public and secret key created and signed. + +pub rsa4096 2022-07-12 [SC] + F77B887A4F25A9468C513E9AA3008E49B00F626B +uid [ultimate] hulk <hulk@apache.org> +sub rsa4096 2022-07-12 [E] +
Firstly, list your key:
gpg --list-keys +
The output is like:
------------------------------- +pub rsa4096 2022-07-12 [SC] + F77B887A4F25A9468C513E9AA3008E49B00F626B +uid [ultimate] hulk <hulk@apache.org> +sub rsa4096 2022-07-12 [E] +
Then, send your key id to key server:
gpg --keyserver keys.openpgp.org --send-key <key-id> # e.g., F77B887A4F25A9468C513E9AA3008E49B00F626B +
Among them, keys.openpgp.org is a randomly selected keyserver, you can use keyserver.ubuntu.com or any other full-featured keyserver.
keys.openpgp.org
keyserver.ubuntu.com
Uploading takes about one minute; after that, you can check by your email at the corresponding keyserver.
Uploading keys to the keyserver is mainly for joining a Web of Trust.
:::info
SVN
:::
The svn repository of the release branch is: https://dist.apache.org/repos/dist/release/iceberg
Please always add the public key to KEYS in the release branch:
svn co https://dist.apache.org/repos/dist/release/iceberg iceberg-dist +# As this step will copy all the versions, it will take some time. If the network is broken, please use svn cleanup to delete the lock before re-execute it. +cd iceberg-dist +(gpg --list-sigs YOUR_NAME@apache.org && gpg --export --armor YOUR_NAME@apache.org) >> KEYS # Append your key to the KEYS file +svn add . # It is not needed if the KEYS document exists before. +svn ci -m "add gpg key for YOUR_NAME" # Later on, if you are asked to enter a username and password, just use your apache username and password. +