diff --git a/dev/release/README.md b/dev/release/README.md index 177f33bcbb4d..d2d9e48bbb6b 100644 --- a/dev/release/README.md +++ b/dev/release/README.md @@ -21,29 +21,24 @@ ## Overview -This file documents the release process for: - -1. The "Rust Arrow Crates": `arrow`, `arrow-flight`, `parquet`, and `parquet-derive`. -2. The `object_store` crate. +This file documents the release process for the "Rust Arrow Crates": `arrow`, `arrow-flight`, `parquet`, and `parquet-derive`. ### The Rust Arrow Crates -The Rust Arrow Crates are interconnected (e.g. `parquet` has an optional dependency on `arrow`) so we increment and release all of them together. We try to release a new version of "Rust Arrow Crates" every two weeks. This cadence balances getting new features into the community without overwhelming downstream projects with too frequent changes or overly burdening maintainers. - -If any code has been merged to master that has a breaking API change, as defined in [Rust RFC 1105](https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md), the major version number incremented changed (e.g. `9.0.2` to `9.0.2`). Otherwise the new minor version incremented (e.g. `9.0.2` to `7.1.0`). - -### `object_store` crate +The Rust Arrow Crates are interconnected (e.g. `parquet` has an optional dependency on `arrow`) so we increment and release all of them together. -At the time of writing, we release a new version of `object_store` on demand rather than on a regular schedule. +If any code has been merged to master that has a breaking API change, as defined +in [Rust RFC 1105] he major version number is incremented (e.g. `9.0.2` to `10.0.2`). +Otherwise the new minor version incremented (e.g. `9.0.2` to `9.1.0`). -As we are still in an early phase, we use the 0.x version scheme. If any code has been merged to master that has a breaking API change, as defined in [Rust RFC 1105](https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md), the minor version number incremented changed (e.g. `0.3.0` to `0.4.0`). Otherwise the patch version is incremented (e.g. `0.3.0` to `0.3.1`). +[rust rfc 1105]: https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md # Release Mechanics ## Process Overview As part of the Apache governance model, official releases consist of -signed source tarballs approved by the PMC. +signed source tarballs approved by the Arrow PMC. We then use the code in the approved source tarball to release to crates.io, the Rust ecosystem's package manager. @@ -60,9 +55,7 @@ labels associated with them. Now prepare a PR to update `CHANGELOG.md` and versions on `master` to reflect the planned release. -For the Rust Arrow crates, do this in the root of this repository. For example [#2323](https://github.com/apache/arrow-rs/pull/2323) - -For `object_store` the same process is done in the `object_store` directory. Examples TBD +Do this in the root of this repository. For example [#2323](https://github.com/apache/arrow-rs/pull/2323) ```bash git checkout master @@ -90,7 +83,6 @@ python dev/release/label_issues.py # review change log / edit issues and labels if needed, rerun git commit -a -m 'Create changelog' - # Manually edit ./dev/release/update_change_log.sh to reflect the release version # Create the changelog CHANGELOG_GITHUB_TOKEN= ./dev/release/update_change_log.sh @@ -98,9 +90,6 @@ CHANGELOG_GITHUB_TOKEN= ./dev/release/update_change_log.sh git commit -a -m 'Create changelog' git push - -# File the release PR -export BRANCH= && export GITHUB_USERNAME= && export GITHUB_TOKEN= && ./file_release_pr.sh ``` Note that when reviewing the change log, rather than editing the @@ -120,9 +109,7 @@ distribution servers. While the official release artifact is a signed tarball, we also tag the commit it was created for convenience and code archaeology. -For a Rust Arrow Crates release, use a string such as `4.0.1` as the ``. - -For `object_store` releases, use a string such as `object_store_0.4.0` as the ``. +Use a string such as `43.0.0` as the ``. Create and push the tag thusly: @@ -147,12 +134,6 @@ Rust Arrow Crates: ./dev/release/create-tarball.sh 4.1.0 2 ``` -`object_store`: - -```shell -./object_store/dev/release/create-tarball.sh 4.1.0 2 -``` - The `create-tarball.sh` script 1. creates and uploads a release candidate tarball to the [arrow @@ -198,7 +179,7 @@ For the release to become "official" it needs at least three Apache Arrow PMC me ## Verifying release candidates -The `dev/release/verify-release-candidate.sh` or `object_store/dev/release/verify-release-candidate.sh` are scripts in this repository that can assist in the verification process. Run it like: +The `dev/release/verify-release-candidate.sh` script in this repository can assist in the verification process. Run it like: ``` ./dev/release/verify-release-candidate.sh 4.1.0 2 @@ -218,19 +199,13 @@ Rust Arrow Crates: ./dev/release/release-tarball.sh 4.1.0 2 ``` -`object_store` - -```shell -./object_store/dev/release/release-tarball.sh 4.1.0 2 -``` - Congratulations! The release is now official! ### Publish on Crates.io -Only approved releases of the tarball should be published to -crates.io, in order to conform to Apache Software Foundation -governance standards. +It is important that only approved releases of the tarball should be published +to crates.io, in order to conform to Apache Software Foundation governance +standards. An Arrow committer can publish this crate after an official project release has been made to crates.io using the following instructions. @@ -269,9 +244,3 @@ Rust Arrow Crates: (cd parquet_derive && cargo publish) (cd arrow-integration-test && cargo publish) ``` - -`object_store` - -```shell -cargo publish -``` diff --git a/dev/release/file_release_pr.sh b/dev/release/file_release_pr.sh deleted file mode 100644 index 081b7c436aa5..000000000000 --- a/dev/release/file_release_pr.sh +++ /dev/null @@ -1,40 +0,0 @@ -#!/bin/bash -# -# Licensed to the Apache Software Foundation (ASF) under one -# or more contributor license agreements. See the NOTICE file -# distributed with this work for additional information -# regarding copyright ownership. The ASF licenses this file -# to you 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. -# -# generates a standard release PR like this: -# https://github.com/apache/arrow-rs/pull/2734 -# -# Usage: -# export BRANCH= && export GITHUB_USERNAME= && export GITHUB_TOKEN= && ./file_release_pr.sh - -set -e - -FUTURE_RELEASE="35.0.0" -ISSUE_NUMBER=3830 - -TITLE="Update version to \`$FUTURE_RELEASE\` and update \`CHANGELOG\`" -BODY="# Which issue does this PR close?\n\nCloses #$ISSUE_NUMBER.\n\n# Rationale for this change\nPrepare for biweekly release\n\n# What changes are included in this PR?\n\n# Are there any user-facing changes?\nYes" -DATA="{\"title\":\"$TITLE\", \"body\":\"$BODY\", \"head\":\"$GITHUB_USERNAME:$BRANCH\",\"base\":\"master\"}" - -# Create the pull request -curl -X POST \ - -H "Accept: application/vnd.github+json" \ - -H "Authorization: Bearer $GITHUB_TOKEN" \ - https://api.github.com/repos/apache/arrow-rs/pulls \ - -d "$DATA" diff --git a/object_store/dev/release/README.md b/object_store/dev/release/README.md index 89f6e579b23d..4077dcad9653 100644 --- a/object_store/dev/release/README.md +++ b/object_store/dev/release/README.md @@ -17,4 +17,209 @@ under the License. --> -See instructions in [`/dev/release/README.md`](../../../dev/release/README.md) + +# Release Process + +## Overview + +This file documents the release process for the `object_store` crate. + +At the time of writing, we release a new version of `object_store` on demand rather than on a regular schedule. + +As we are still in an early phase, we use the 0.x version scheme. If any code has +been merged to master that has a breaking API change, as defined in [Rust RFC 1105] +the minor version number is incremented changed (e.g. `0.3.0` to `0.4.0`). +Otherwise the patch version is incremented (e.g. `0.3.0` to `0.3.1`). + +[Rust RFC 1105]: https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md +# Release Mechanics + +## Process Overview + +As part of the Apache governance model, official releases consist of +signed source tarballs approved by the PMC. + +We then use the code in the approved source tarball to release to +crates.io, the Rust ecosystem's package manager. + +We create a `CHANGELOG.md` so our users know what has been changed between releases. + +The CHANGELOG is created automatically using +[update_change_log.sh](https://github.com/apache/arrow-rs/blob/master/object_store/dev/release/update_change_log.sh) + +This script creates a changelog using github issues and the +labels associated with them. + +## Prepare CHANGELOG and version: + +Now prepare a PR to update `CHANGELOG.md` and versions on `master` to reflect the planned release. + +Note this process is done in the `object_store` directory. See [#6227] for an example + +[#6227]: https://github.com/apache/arrow-rs/pull/6227 + +```bash +# NOTE: Run commands in object_store sub directory (not main repo checkout) +# cd object_store + +git checkout master +git pull +git checkout -b + +# Update versions. Make sure to run it before the next step since we do not want CHANGELOG-old.md affected. +sed -i '' -e 's/0.11.0/0.11.1/g' `find . -name 'Cargo.toml' -or -name '*.md' | grep -v CHANGELOG` +git commit -a -m 'Update version' + +# ensure your github token is available +export CHANGELOG_GITHUB_TOKEN= + +# manually edit ./dev/release/update_change_log.sh to reflect the release version +# create the changelog +./dev/release/update_change_log.sh + +# review change log / and edit associated issues and labels if needed, rerun update_change_log.sh + +# Commit changes +git commit -a -m 'Create changelog' + +# push changes to fork and create a PR to master +git push +``` + +Note that when reviewing the change log, rather than editing the +`CHANGELOG.md`, it is preferred to update the issues and their labels +(e.g. add `invalid` label to exclude them from release notes) + +Merge this PR to `master` prior to the next step. + +## Prepare release candidate tarball + +After you have merged the updates to the `CHANGELOG` and version, +create a release candidate using the following steps. Note you need to +be a committer to run these scripts as they upload to the apache `svn` +distribution servers. + +### Create git tag for the release: + +While the official release artifact is a signed tarball, we also tag the commit it was created for convenience and code archaeology. + +For `object_store` releases, use a string such as `object_store_0.4.0` as the ``. + +Create and push the tag thusly: + +```shell +git fetch apache +git tag apache/master +# push tag to apache +git push apache +``` + +### Pick an Release Candidate (RC) number + +Pick numbers in sequential order, with `1` for `rc1`, `2` for `rc2`, etc. + +### Create, sign, and upload tarball + +Run `create-tarball.sh` with the `` tag and `` and you found in previous steps. + +```shell +./object_store/dev/release/create-tarball.sh 0.11.1 1 +``` + +The `create-tarball.sh` script + +1. creates and uploads a release candidate tarball to the [arrow + dev](https://dist.apache.org/repos/dist/dev/arrow) location on the + apache distribution svn server + +2. provide you an email template to + send to dev@arrow.apache.org for release voting. + +### Vote on Release Candidate tarball + +Send an email, based on the output from the script to dev@arrow.apache.org. The email should look like + +``` +Draft email for dev@arrow.apache.org mailing list + +--------------------------------------------------------- +To: dev@arrow.apache.org +Subject: [VOTE][RUST] Release Apache Arrow Rust Object Store 0.11.1 RC1 + +Hi, + +I would like to propose a release of Apache Arrow Rust Object +Store Implementation, version 0.11.1. + +This release candidate is based on commit: b945b15de9085f5961a478d4f35b0c5c3427e248 [1] + +The proposed release tarball and signatures are hosted at [2]. + +The changelog is located at [3]. + +Please download, verify checksums and signatures, run the unit tests, +and vote on the release. There is a script [4] that automates some of +the verification. + +The vote will be open for at least 72 hours. + +[ ] +1 Release this as Apache Arrow Rust Object Store +[ ] +0 +[ ] -1 Do not release this as Apache Arrow Rust Object Store because... + +[1]: https://github.com/apache/arrow-rs/tree/b945b15de9085f5961a478d4f35b0c5c3427e248 +[2]: https://dist.apache.org/repos/dist/dev/arrow/apache-arrow-object-store-rs-0.11.1-rc1 +[3]: https://github.com/apache/arrow-rs/blob/b945b15de9085f5961a478d4f35b0c5c3427e248/object_store/CHANGELOG.md +[4]: https://github.com/apache/arrow-rs/blob/master/object_store/dev/release/verify-release-candidate.sh +``` + +For the release to become "official" it needs at least three Apache Arrow PMC members to vote +1 on it. + +## Verifying release candidates + +The `object_store/dev/release/verify-release-candidate.sh` script can assist in the verification process. Run it like: + +``` +./object_store/dev/release/verify-release-candidate.sh 0.11.0 1 +``` + +#### If the release is not approved + +If the release is not approved, fix whatever the problem is and try again with the next RC number + +### If the release is approved, + +Move tarball to the release location in SVN, e.g. https://dist.apache.org/repos/dist/release/arrow/arrow-4.1.0/, using the `release-tarball.sh` script: + + +```shell +./object_store/dev/release/release-tarball.sh 4.1.0 2 +``` + +Congratulations! The release is now official! + +### Publish on Crates.io + +Only approved releases of the tarball should be published to +crates.io, in order to conform to Apache Software Foundation +governance standards. + +An Arrow committer can publish this crate after an official project release has +been made to crates.io using the following instructions. + +Follow [these +instructions](https://doc.rust-lang.org/cargo/reference/publishing.html) to +create an account and login to crates.io before asking to be added as an owner +of the [arrow crate](https://crates.io/crates/arrow). + +Download and unpack the official release tarball + +Verify that the Cargo.toml in the tarball contains the correct version +(e.g. `version = "0.11.0"`) and then publish the crate with the +following commands + + +```shell +cargo publish +``` +