This is an automated email from the ASF dual-hosted git repository.
alamb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git
The following commit(s) were added to refs/heads/master by this push:
new 7900b4db8 Update `object_store` release documentation (#6565)
7900b4db8 is described below
commit 7900b4db8e6daf87f72cbd1a18df52b7fa497510
Author: Andrew Lamb <[email protected]>
AuthorDate: Wed Oct 16 06:26:14 2024 -0400
Update `object_store` release documentation (#6565)
* Update object_store release documentation
* Update object store
* prettier
* tweak
* Update object_store/dev/release/README.md
* update instructions
* fix
* Update object_store/dev/release/README.md
---
dev/release/README.md | 57 +++-------
dev/release/file_release_pr.sh | 40 -------
object_store/dev/release/README.md | 207 ++++++++++++++++++++++++++++++++++++-
3 files changed, 219 insertions(+), 85 deletions(-)
diff --git a/dev/release/README.md b/dev/release/README.md
index 177f33bcb..d2d9e48bb 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=<TOKEN> ./dev/release/update_change_log.sh
@@ -98,9 +90,6 @@ CHANGELOG_GITHUB_TOKEN=<TOKEN>
./dev/release/update_change_log.sh
git commit -a -m 'Create changelog'
git push
-
-# File the release PR
-export BRANCH=<RELEASE_BRANCH> && export GITHUB_USERNAME=<USERNAME> && export
GITHUB_TOKEN=<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
`<version>`.
-
-For `object_store` releases, use a string such as `object_store_0.4.0` as the
`<version>`.
+Use a string such as `43.0.0` as the `<version>`.
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 081b7c436..000000000
--- 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=<RELEASE_BRANCH> && export GITHUB_USERNAME=<USERNAME> &&
export GITHUB_TOKEN=<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 89f6e579b..4077dcad9 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 <RELEASE_BRANCH>
+
+# 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=<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
`<version>`.
+
+Create and push the tag thusly:
+
+```shell
+git fetch apache
+git tag <version> apache/master
+# push tag to apache
+git push apache <version>
+```
+
+### 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 `<version>` tag and `<rc>` 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 [email protected] for release voting.
+
+### Vote on Release Candidate tarball
+
+Send an email, based on the output from the script to [email protected].
The email should look like
+
+```
+Draft email for [email protected] mailing list
+
+---------------------------------------------------------
+To: [email protected]
+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
+```
+
