zeroshade commented on code in PR #53: URL: https://github.com/apache/terraform-provider-iceberg/pull/53#discussion_r3554390625
########## .github/workflows/tf-release.yml: ########## @@ -0,0 +1,171 @@ +# 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. + +# On a release-candidate tag (e.g. v0.7.0-rc1), builds the source tarball and +# convenience binaries and publishes them as a GitHub prerelease. The release +# manager drives the rest from dev/release/release_rc.sh (see docs/releasing.md); +# CI never signs. + +name: Terraform Build Release Candidate + +on: + push: + tags: + # RC tags only; the final vX.Y.Z tag is published by release.sh. + - 'v*-rc*' + +concurrency: + group: ${{ github.repository }}-${{ github.ref }}-${{ github.workflow }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + source-release: + name: Build source distribution + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + fetch-depth: 0 + + - name: Determine version + id: version + env: + TAG: ${{ github.ref_name }} + run: | + # v0.7.0-rc1 -> version=0.7.0, rc=1 + version=${TAG#v} + version=${version%-rc*} + rc=${TAG##*-rc} + echo "version=${version}" >> "$GITHUB_OUTPUT" + echo "rc=${rc}" >> "$GITHUB_OUTPUT" + + - name: Build source tarball + env: + VERSION: ${{ steps.version.outputs.version }} + RC: ${{ steps.version.outputs.rc }} + run: | + # -rc in the filename, but unpacks to a dir without it so the tree + # matches the final release. + dir="apache-iceberg-terraform-${VERSION}" + tar_gz="apache-iceberg-terraform-${VERSION}-rc${RC}.tar.gz" + git archive --format=tar.gz --prefix="${dir}/" -o "${tar_gz}" HEAD + sha512sum "${tar_gz}" > "${tar_gz}.sha512" + + - name: Upload source artifact + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 Review Comment: Nit (non-blocking): `upload-artifact` is pinned to v4.6.2 here (and `download-artifact` to v4.3.0 at L149/L155), whereas the sibling `apache/iceberg-go` repo is on v7/v8. v4 upload paired with v4 download is internally consistent and correct, so this isn't a bug — just flagging in case you'd like to keep the toolchain aligned across the two repos. ########## .goreleaser.yml: ########## @@ -0,0 +1,92 @@ +# 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. + +# GoReleaser configuration for the Iceberg Terraform provider. +# +# This produces the *convenience binaries* consumed by the Terraform Registry +# (registry.terraform.io/apache/iceberg) and the OpenTofu Registry. It is NOT +# the official Apache release artifact -- that is the source tarball that is +# voted on (see docs/releasing.md). +# +# The official binary layout required by the registries is documented at +# https://developer.hashicorp.com/terraform/registry/providers/publishing +# +# Signing of the SHA256SUMS file is performed locally by the release manager +# with their KEYS-registered GPG key, so the `signs` block below is skipped in +# CI (`--skip=sign`). See docs/releasing.md for the manual signing step. +version: 2 + +# The Terraform Registry requires the binary and archives to be named +# `terraform-provider-iceberg`. The upstream repo apache/terraform-provider-iceberg +# already yields this name by default; pin it so a contributor's differently-named +# fork still produces correct artifacts. +project_name: terraform-provider-iceberg + +before: + hooks: + - go mod tidy Review Comment: `go mod tidy` as a release hook can mutate `go.mod`/`go.sum` and shift the module graph relative to what was voted on. On a clean tagged checkout it should be a no-op, but `go mod download` is the safer choice here since it fetches dependencies without rewriting the module files. (This only affects the binary-release job; the source tarball is produced by `git archive` in a separate job, so it's low risk either way.) ########## docs/releasing.md: ########## @@ -0,0 +1,304 @@ +<!-- + - 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. + --> + +# How to Release + +This guide outlines the process for releasing the Apache Iceberg Terraform +provider in accordance with the [Apache Release Process](https://infra.apache.org/release-publishing.html). +The steps include: + +1. Preparing for a release +2. Publishing a Release Candidate (RC) +3. Community Voting and Validation +4. Publishing the Final Release (if the vote passes) +5. Post-Release Steps + +## Requirements + +* A GPG key must be registered and published in the + [Apache Iceberg KEYS file](https://downloads.apache.org/iceberg/KEYS). Follow + [the instructions for setting up a GPG key and uploading it to the KEYS file](#set-up-gpg-key-and-upload-to-apache-iceberg-keys-file). + * Permission to update the `KEYS` artifact in the + [Apache release distribution](https://dist.apache.org/repos/dist/release/iceberg/) + (requires Iceberg PMC privileges). +* SVN Access + * Permission to upload artifacts to the + [Apache development distribution](https://dist.apache.org/repos/dist/dev/iceberg/) + (requires Apache Committer access). + * Permission to upload artifacts to the + [Apache release distribution](https://dist.apache.org/repos/dist/release/iceberg/) + (requires Apache PMC access). +* Terraform / OpenTofu Registry Access + * The [`apache` namespace on the Terraform Registry](https://registry.terraform.io/providers/apache) + must have the `terraform-provider-iceberg` provider claimed, with the + release manager's GPG public key (the same key in `KEYS`) registered under + **Settings → GPG Keys**. The OpenTofu Registry mirrors GitHub Releases for + the same namespace and requires no separate upload. +* Tooling installed locally + * `git`, `svn`, `gpg`, and `shasum`/`sha512sum`. + * [`gh`](https://cli.github.com/) (GitHub CLI), used to watch the build and + create the final GitHub Release. + * [`goreleaser`](https://goreleaser.com/install/) (v2), only needed if you + want to reproduce the convenience binaries locally; the GitHub Action + builds them for you. + +## Preparing for a Release + +Before cutting a release candidate: + +* **Remove deprecated attributes and resources** scheduled for removal in this + version — schema attributes, resources, and data sources carrying a + `DeprecationMessage`, and Go symbols marked `// Deprecated:` — and update the + `docs/` and `examples/` that reference them. +* **Confirm the provider address** in [`main.go`](../main.go) is + `registry.terraform.io/apache/iceberg`. + +## Publishing a Release Candidate (RC) + +### Versioning + +The **git tag** carries the version. There is no version string to bump in a +source file (unlike `pyproject.toml` for PyIceberg) — the registry and GoReleaser +both derive the version from the tag. You choose the version when you create the +tag, below. + +Versions follow [semantic versioning](https://semver.org/) with a `v` prefix +(`v0.7.0`). Release candidates add a `-rcN` suffix (`v0.7.0-rc1`). + + +### Release Types + +#### Major/Minor Release + +* Use the `main` branch for the release. +* Includes new features, enhancements, and any necessary backward-compatible + changes. +* Examples: `v0.8.0`, `v0.9.0`, `v1.0.0`. + +#### Patch Release + +* Use the branch corresponding to the patch version, such as + `iceberg-terraform-0.8.x`. +* Focuses on critical bug fixes or security patches that maintain backward + compatibility. +* Examples: `v0.8.1`, `v0.8.2`. + +To create a patch branch from the latest release tag: + +```bash +# Fetch all tags +git fetch --tags + +# Assuming v0.8.0 is the latest release tag +git checkout -b iceberg-terraform-0.8.x v0.8.0 + +# Cherry-pick commits for the upcoming patch release +git cherry-pick <commit> + +# Push the new branch +git push [email protected]:apache/terraform-provider-iceberg.git iceberg-terraform-0.8.x +``` + +### Cut the Release Candidate + +From a clean checkout on the correct branch (`main` for a major/minor release, +`iceberg-terraform-X.Y.x` for a patch), run: + +```bash +./dev/release/release_rc.sh <version> <rc> +# e.g. ./dev/release/release_rc.sh 0.7.0 1 +``` + +The script: + +1. Tags `v<version>-rc<rc>` and pushes it, which triggers the + [`Terraform Build Release Candidate`](../.github/workflows/tf-release.yml) + workflow. The workflow builds the source tarball and the convenience binaries + and publishes them as a GitHub **prerelease**. +2. Waits for the workflow, downloads the artifacts, and signs them with your + KEYS-registered GPG key — a detached `.asc` over the source tarball and a + detached `.sig` over the binary `SHA256SUMS` — then uploads the signatures + back onto the prerelease. +3. Uploads the signed **source** release to the Apache dev SVN at + `dev/iceberg/apache-iceberg-terraform-<version>-rc<rc>/`. Only the source is + voted on and archived in SVN; the convenience binaries stay on the GitHub + prerelease. +4. Prints the `[VOTE]` email. + +Set `RELEASE_PUSH_TAG=0`, `RELEASE_SIGN=0`, or `RELEASE_UPLOAD=0` (or +`RELEASE_DEFAULT=0`) to dry-run individual stages — for example, to re-run +signing without re-tagging. + +> **Note:** Only 64-bit targets (`amd64`, `arm64`) are built for +> linux/darwin/windows/freebsd. A dependency (`github.com/apache/thrift`, via +> `iceberg-go`) does not compile on 32-bit. See +> [`.goreleaser.yml`](../.goreleaser.yml). + +## Vote + +Review the `[VOTE]` email the script printed, add a summary of the high-level +features, and send it to `[email protected]`. The vote runs for at least +72 hours and needs at least 3 binding +1 votes to pass. + +### Vote has failed + +If there are concerns with the RC, address them and cut another candidate by +re-running the script with the next RC number: + +```bash +./dev/release/release_rc.sh <version> <next-rc> +``` + +## Publish the Final Release (Vote has passed) + +An RC passes with at least 3 binding +1 votes. Once it passes, close the vote +thread: + +```text +Thanks everyone for voting! The 72 hours have passed, and a minimum of 3 binding +votes have been cast: + ++1 Foo Bar (non-binding) +... ++1 Fokko Driesprong (binding) + +The release candidate has been accepted as Apache Iceberg Terraform provider +<VERSION>. Thanks everyone; when all artifacts are published the announcement +will be sent out. + +Kind regards, +``` + +Then finalize the release. From a clean checkout, run the script with the +version and the RC number that passed the vote: + +```bash +./dev/release/release.sh <version> <rc> +# e.g. ./dev/release/release.sh 0.7.0 1 +``` + +The script: + +1. Tags `v<version>` at the RC commit and pushes it. +2. Moves the **source** release from the dev SVN to the release SVN at + `release/iceberg/apache-iceberg-terraform-<version>/`, and removes the now + superseded RC folder from the dev SVN. +3. Creates the final (non-prerelease) GitHub release, attaching the promoted + source release and the **already-signed** convenience binaries from the RC + prerelease. Nothing is rebuilt, so what users install is bit-for-bit what was + voted on. The Terraform and OpenTofu registries ingest this release. +4. Removes superseded releases from the release SVN, keeping only the latest. + +> **Note:** Moving artifacts into the release SVN requires Iceberg PMC +> privileges. Work with a PMC member if you do not have them. + +The final GitHub release carries exactly the files the registry requires: one +`terraform-provider-iceberg_<version>_<os>_<arch>.zip` per platform, one +`..._SHA256SUMS`, one `..._SHA256SUMS.sig` signed by the KEYS-registered key, +and one `..._manifest.json`. + +Within a few minutes the +[Terraform Registry](https://registry.terraform.io/providers/apache/iceberg) and +[OpenTofu Registry](https://search.opentofu.org/provider/apache/iceberg) detect +the release and publish the new version. Verify it appears, then run +`terraform init` against a configuration pinning the new version to confirm it +installs. + +## Post Release + +### Send out Release Announcement Email + +Send an announcement to the dev mailing list: + +```text +To: [email protected] +Subject: [ANNOUNCE] Apache Iceberg Terraform provider <VERSION> + +I'm pleased to announce the release of the Apache Iceberg Terraform provider +<VERSION>! + +Apache Iceberg is an open table format for huge analytic datasets. This Terraform +(and OpenTofu) provider lets you manage Iceberg resources -- such as namespaces +and tables -- as infrastructure as code. + +The provider can be used from the Terraform Registry: +https://registry.terraform.io/providers/apache/iceberg/<VERSION> + +and the OpenTofu Registry: +https://search.opentofu.org/provider/apache/iceberg/<VERSION> + +Thanks to everyone for contributing! +``` + +### Create a GitHub Release Note + +`release.sh` already created the GitHub release with auto-generated notes. Open +it in the browser, refine the notes if needed (the **Generate release notes** +button, with the previous release tag as the **Previous tag**), and confirm it is +marked as the latest release. Check the `changelog` label on GitHub for anything +worth highlighting. + +### Update the GitHub Issue Template + +Create a PR to add the new version to the +[GitHub issue template](https://github.com/apache/terraform-provider-iceberg/tree/main/.github/ISSUE_TEMPLATE) +version dropdown (if present). + +## Verifying a Release + +Reviewers validate a candidate with: + +```bash +./dev/release/verify_rc.sh <version> <rc> +# e.g. ./dev/release/verify_rc.sh 0.7.0 1 +``` + +The script imports the Apache Iceberg `KEYS`, downloads the source release from +the dev SVN, verifies its GPG signature and SHA-512 checksum, runs the Apache +RAT license check, and builds and tests the provider from source in a throwaway Review Comment: The RAT license check runs via `verify_rc.sh` -> `dev/check-license`, which downloads the Apache RAT `.jar` and executes it under `java` (and uses `unzip` to validate the jar). Neither `java` (a JDK) nor `unzip` is listed in the verification prerequisites, so a voter on a machine without a JDK will hit a hard failure at this step. Consider either adding `java`/`unzip` to the verify prerequisites, or explicitly documenting that `VERIFY_RAT=0` skips this check. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
