This is an automated email from the ASF dual-hosted git repository.
jorisvandenbossche pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new 0f6cb888f1 ARROW-13844: [Docs][Release] Add Release Management Guide
to Dev docs (#13272)
0f6cb888f1 is described below
commit 0f6cb888f176591ac02e4f8b29ab00a5d9c19908
Author: Raúl Cumplido <[email protected]>
AuthorDate: Thu Jun 2 14:14:14 2022 +0200
ARROW-13844: [Docs][Release] Add Release Management Guide to Dev docs
(#13272)
Authored-by: Raúl Cumplido <[email protected]>
Signed-off-by: Joris Van den Bossche <[email protected]>
---
docs/source/developers/release.rst | 290 +++++++++++++++++++++++++++++++++++++
docs/source/index.rst | 1 +
2 files changed, 291 insertions(+)
diff --git a/docs/source/developers/release.rst
b/docs/source/developers/release.rst
new file mode 100644
index 0000000000..45eabb56f6
--- /dev/null
+++ b/docs/source/developers/release.rst
@@ -0,0 +1,290 @@
+.. 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.
+
+========================
+Release Management Guide
+========================
+
+This page provides detailed information on the steps followed to perform
+a release. It can be used both as a guide to learn the Apache Arrow release
+process and as a comprehensive checklist for the Release Manager when
+performing a release.
+
+Principles
+==========
+
+The Apache Arrow Release follows the guidelines defined at the
+`Apache Software Foundation Release Policy
<https://www.apache.org/legal/release-policy.html>`_.
+
+Preparing for the release
+=========================
+
+Before creating a source release, the Release Manager must ensure that any
+resolved JIRAs have the appropriate Fix Version set so that the changelog is
+generated properly.
+
+.. dropdown:: Requirements
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-md
+
+ Some steps of the release require being a committer or a PMC member.
+
+ - Install the :ref:`Archery <archery>` utility which is required for the
release.
+ - You must not have any arrow-cpp or parquet-cpp environment variables
defined except CC or CXX if you want to build with something other than GCC by
default (e.g. clang).
+ - A GPG key in the Apache Web of Trust to sign artifacts. This will have
to be cross signed by other Apache committers/PMC members. If you have multiple
GPG keys, you must set the correct GPG key ID in ``~/.gnupg/gpg.conf`` by
adding:
+
+ .. code-block::
+
+ default-key ${YOUR_GPG_KEY_ID}
+
+ - The GPG key needs to be added to this `SVN repo
<https://dist.apache.org/repos/dist/dev/arrow/>`_ and `this one
<https://dist.apache.org/repos/dist/release/arrow/>`_.
+ - Configure Maven to `publish artifacts to Apache repositories
<http://www.apache.org/dev/publishing-maven-artifacts.html>`_. You will need to
`setup a master password
<https://maven.apache.org/guides/mini/guide-encryption.html>`_ at
``~/.m2/settings-security.xml`` and ``settings.xml`` as specified on the
`Apache guide
<http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env>`_. It can
be tested with the following command:
+
+ .. code-block::
+
+ # You might need to export GPG_TTY=$(tty) to properly prompt for a
passphrase
+ mvn clean install -Papache-release
+
+ - Have the build requirements for cpp and c_glib installed.
+ - Set the JIRA_USERNAME and JIRA_PASSWORD environment variables
+ - Install ``en_US.UTF-8`` locale. You can confirm available locales by
``locale -a``.
+ - Install Python 3 as python
+ - Create dev/release/.env from dev/release/.env.example. See the comments
in dev/release/.env.example how to set each variable.
+ - Request to the Apache INFRA group to be aadded to `Bintray members
<https://bintray.com/apache/>`_.
+ - Setup :ref:`Crossbow<Crossbow>` as defined.
+ - Have Docker and docker-compose installed.
+
+
+Creating a Release Candidate
+============================
+
+These are the different steps that are required to create a release candidate.
+
+.. code-block::
+
+ # Delete the local tag and release branch for RC1 or later
+ git branch -d release-<version>
+ git tag -d apache-arrow-<version>
+
+ # Setup gpg agent for signing artifacts
+ source dev/release/setup-gpg-agent.sh
+
+ # Curate the release
+ # The end of the generated report shows the jira tickets with wrong
version number assigned.
+ archery release curate <version>
+
+ # Checkout release branch
+ # Use master for major releases
+ git checkout -b release-4.0.0 master
+ # Use maintenance branches like maint-4.0.x for patch releases
+ git checkout -b release-4.0.1 maint-4.0.x
+
+ # Create branch for the release candidate and place the necessary commits
then create git tag
+ # on OSX use gnu-sed with homebrew: brew install gnu-sed (and export to
$PATH)
+ #
+ # <rc-number> starts at 0 and increments every time the release candidate
is burned
+ # so for the first RC this would be: dev/release/01-prepare.sh 4.0.0 5.0.0 0
+ dev/release/01-prepare.sh <version> <next-version> <rc-number>
+
+ # Push the release branch and release tag (for RC1 or later the --force
flag is required)
+ git push -u apache release-<version>
+ git push -u apache apache-arrow-<version>
+
+ # Build the source release tarball
+ dev/release/02-source.sh <version> <rc-number>
+
+ # Submit binary tasks using crossbow, the command will output the crossbow
build id
+ dev/release/03-binary-submit.sh <version> <rc-number>
+
+ # Wait for the crossbow jobs to finish
+ archery crossbow status <crossbow-build-id>
+
+ # Download the produced binaries
+ # This will download packages to a directory called
packages/release-<version>-rc<rc-number>
+ dev/release/04-binary-download.sh <version> <rc-number>
+
+ # Sign and upload the binaries
+ #
+ # On macOS the only way I could get this to work was running "echo
"UPDATESTARTUPTTY" | gpg-connect-agent" before running this comment
+ # otherwise I got errors referencing "ioctl" errors.
+ dev/release/05-binary-upload.sh <version> <rc-number>
+
+ # Sign and upload the Java artifacts
+ #
+ # Note that you need to press the "Close" button manually by Web interfacec
+ # after you complete the script:
+ # https://repository.apache.org/#stagingRepositories
+ dev/release/06-java-upload.sh <version> <rc-number>
+
+ # Automatically verify the release candidate
+ #
+ # 1. Push the release candidate's branch to the fork
+ git push --set-upstream origin release-<version>-rc<rc-number>
+ # 2. Open a pull request from the release candidate's branch to the
release branch
+ #
https://github.com/apache/arrow/compare/release-<version>...<fork-github-username>:release-<version>-rc<rc-number>
+ # 3. Create a comment for the pull request to trigger the automatized
crossbow verification tasks
+ # @github-actions crossbow submit --group verify-rc-source --group
verify-rc-binaries --group verify-rc-wheels --param release=<version> --param
rc=<rc-number>
+ #
+ # See https://github.com/apache/arrow/pull/10126 as an example.
+
+ # Once the automatic verification has passed merge the release candidate's
branch to the release branch
+ # may need the --force flag to push the release-<version> branch to the
apache remote for RC1 or later
+ git checkout release-<version>
+ git merge release-<version>-rc<rc-number>
+ git push apache release-<version>
+
+ # Start the vote thread on [email protected]
+ # To regenerate the email template use
+ SOURCE_DEFAULT=0 SOURCE_VOTE=1 dev/release/02-source.sh <version>
<rc-number>
+
+Voting and approval
+===================
+
+Start the vote thread on [email protected] and supply instructions for
verifying the integrity of the release.
+Approval requires a net of 3 +1 votes from PMC members. A release cannot be
vetoed.
+
+Post-release tasks
+==================
+
+After the release vote, we must undertake many tasks to update source
artifacts, binary builds, and the Arrow website.
+
+Be sure to go through on the following checklist:
+
+#. Make the released version as "RELEASED" on JIRA
+#. Start the new version on JIRA
+#. Merge changes on release branch to maintenance branch for patch releases
+#. Upload source
+#. Upload binaries
+#. Update website
+#. Update Homebrew packages
+#. Update MSYS2 package
+#. Upload RubyGems
+#. Upload JS packages
+#. Upload C# packages
+#. Update conda recipes
+#. Upload wheels/sdist to pypi
+#. Publish Maven artifacts
+#. Update R packages
+#. Update vcpkg port
+#. Bump versions
+#. Update tags for Go modules
+#. Update docs
+#. Remove old artifacts
+
+.. dropdown:: Marking the released version as "RELEASED" on JIRA
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-md
+
+ Open
https://issues.apache.org/jira/plugins/servlet/project-config/ARROW/administer-versions
+
+ Click "..." for the release version in "Actions" column
+
+ Select "Release"
+
+ Set "Release date"
+
+ Click "Release" button
+
+.. dropdown:: Starting the new version on JIRA
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-md
+
+ Open
https://issues.apache.org/jira/plugins/servlet/project-config/ARROW/administer-versions
+
+ Click "..." for the next version in "Actions" column
+
+ Select "Edit"
+
+ Set "Start date"
+
+ Click "Save" button
+
+.. dropdown:: Updating the Arrow website
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-md
+
+ Fork the `arrow-site repository <https://github.com/apache/arrow-site>`_
and clone it next to the arrow repository.
+
+ Generate the release note:
+
+ .. code-block::
+
+ # dev/release/post-03-website 0.13.0 0.14.0
+ dev/release/post-03-website <previous-version> <version>
+
+ Create a pull-request and a Jira with the links the script shows at the
end.
+
+.. dropdown:: Uploading source release artifacts to SVN
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-md
+
+ A PMC member must commit the source release artifacts to SVN:
+
+ .. code-block::
+
+ # dev/release/post-02-upload.sh 0.1.0 0
+ dev/release/post-02-upload.sh <version> <rc>
+
+.. dropdown:: Uploading binary release artifacts to Artifactory
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-md
+
+ A PMC member must upload the binary release artifacts to Artifactory:
+
+ .. code-block::
+
+ # dev/release/post-03-binary.sh 0.1.0 0
+ dev/release/post-03-binary.sh <version> <rc number>
+
+.. dropdown:: Announcing release
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-md
+
+ Add relevant release data for Arrow to `Apache reporter
<https://reporter.apache.org>`_.
+
+ Write a release announcement (see `example
<https://lists.apache.org/thread/6rkjwvyjjfodrxffllh66pcqnp729n3k>`_) and send
to [email protected] and [email protected].
+
+ The announcement to [email protected] must be sent from your apache.org
e-mail address to be accepted.
+
+.. dropdown:: Generating new API documentations and update the website
+ :animate: fade-in-slide-down
+ :class-title: sd-fs-5
+ :class-container: sd-shadow-md
+
+ The API documentation for C++, C Glib, Python, Java, and JavaScript can be
generated via a Docker-based setup.
+ To generate the API documentation run the following command:
+
+ .. code-block::
+
+ # preferred to have a cuda capable device with a recent docker version
to generate the cuda docs as well
+ # if you don't have an nvidia GPU please ask for help on the mailing
list
+ dev/release/post-09-docs.sh <version>
+
+ # without a cuda device it's still possible to generate the apidocs
with the following archery command
+ archery docker run -v "${ARROW_SITE_DIR}/docs:/build/docs" -e
ARROW_DOCS_VERSION="${version}" ubuntu-docs
+
+ Note, that on a case insensitive filesystem sphinx generate duplicate
filenames, so there can be missing links on the documentation page. Please use
a system (preferably Linux) to execute the command above.
+
+ This script assumes that the arrow-site repository is cloned next to the
arrow source repository. Please note that most of the software must be built in
order to create the documentation, so this step may take some time to run,
especially the first time around as the Docker container will also have to be
built.
+
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3898e14f4e..f8d1e71a4f 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -98,4 +98,5 @@ target environment.**
developers/continuous_integration/index
developers/benchmarks
developers/documentation
+ developers/release
developers/computeir
