Add some more documentation

arrow/README.md

@@ -174,33 +174,6 @@ specific JIRA issues and reference them in these code comments. For example:
 //      This is not sound because .... see https://issues.apache.org/jira/browse/ARROW-nnnnn
 ```
 
-# Publishing to crates.io
+# Releases and publishing to crates.io
 
-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).
-
-Checkout the tag for the version to be released. For example:
-
-```bash
-git checkout apache-arrow-0.11.0
-```
-
-If the Cargo.toml in this tag already contains `version = "0.11.0"` (as it
-should) then the crate can be published with the following command:
-
-```bash
-cargo publish
-```
-
-If the Cargo.toml does not have the correct version then it will be necessary
-to modify it manually. Since there is now a modified file locally that is not
-committed to GitHub it will be necessary to use the following command.
-
-```bash
-cargo publish --allow-dirty
-```
+Please see the [release](../dev/release/README.md) for details on how to create arrow releases

dev/release/README.md

@@ -0,0 +1,114 @@
+<!---
+  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 scripts
+
+# Process Overview
+(TODO)
+
+# Mechanics of creating a release
+
+## Prepare active_release
+
+Create and merge a PR to update changelog and versions on `active_release` branch. See [#298](https://github.com/apache/arrow-rs/pull/298) for an example
+
+## Prepare release candidate
+
+(Note you need to be a committer to run these scripts as they upload to the apache svn servers)
+
+### Create git tag for the release:
+
+While the official release artifact is a signed tarball, having a tag to the commit it was created from can be useful for code archaeology.
+
+Using a string such as `4.0.1` as the `<version>`, create and push the tag thusly:
+
+```shell
+git fetch apache
+git tag <version> apache/active_release
+# push tag to apache
+git push <version> apache
+```
+
+### Create, sign, and upload tarball
+
+Run the  `create-tarball.sh` with the `<version>` tag you created in previous steps
+
+This will create and upload a release candidate tarball to the [arrow
+dev](https://dist.apache.org/repos/dist/dev/arrow) location of the
+apache distribution svn server and provide you an email template to
+send to [email protected] for release voting.
+
+
+### Vote on artifact
+
+Send the email such as the following to [email protected]
+
+```
+TODO get from initial
+```
+
+For the release to become "official" it needs at least three PMC members to vote +1 on it.
+
+
+#### If the release is not approved
+
+If the release is not approved, fix whatever the problem is
+and try again
+
+Open question: The simplest process is to make a new minor release version (e.g. if `4.1.1` didn't pass, make `4.1.2`) and run the process again. This would allow us to avoid the overhead of creating  "RC / release candidates but would means published version numbers could have gaps
+
+
+
+### If the release is approved,
+Move tarball to release, e.g. https://dist.apache.org/repos/dist/release/arrow/apache-arrow-rs-4.1.0/
+
+TODO (instructions / script to do this)
+
+### Publish on Crates.io
+
+Using only the released artifact (contents of the tarball):
+
+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).
+
+Checkout the tag for the version to be released. For example:
+
+```bash
+git checkout apache-arrow-0.11.0
+```
+
+If the Cargo.toml in this tag already contains `version = "0.11.0"` (as it
+should) then the crate can be published with the following command:
+
+```bash
+cargo publish
+```
+
+If the Cargo.toml does not have the correct version then it will be necessary
+to modify it manually. Since there is now a modified file locally that is not
+committed to GitHub it will be necessary to use the following command.
+
+```bash
+cargo publish --allow-dirty
+```

dev/release/create-tarball.sh

@@ -19,10 +19,23 @@
 #
 
 
-# This script creates a signed tarball in dev/dist/apache-arrow-<version>.tar.gz
-# and uploads it to the "dev" area of dist.apache.arrow (NOT an official release)
+# This script creates a signed tarball in
+# dev/dist/apache-arrow-<version>.tar.gz and uploads it to the "dev"
+# area of dist.apache.arrow (NOT an official release) and prepares an
+# email for sending to the [email protected] list
+#
+# Instructions for use
+#
+# Ensure you have gpg setup for signing and have
+# uploaded your public signature to https://pgp.mit.edu/
+#
+# Ensure you have tagged the source at the appropriate spot
+
 #
 # Based in part on 02-source.sh from apache/arrow
+#
+
+### TODO: put the gitsha somewhere in the tarball
 
 set -e