Merge pull request apache#263 from ballista-compute/documentation/cargo-release-config

add a note about cargo release config

Author: nickolay

.github/workflows/rust.yml

@@ -65,7 +65,7 @@ jobs:
         github-token: ${{ secrets.GITHUB_TOKEN }}
 
   publish-crate:
-    if: startsWith(github.ref, 'refs/tags/')
+    if: startsWith(github.ref, 'refs/tags/v0')
     runs-on: ubuntu-latest
     needs: [test]
     steps:

Cargo.toml

@@ -36,4 +36,7 @@ simple_logger = "1.9"
 matches = "0.1"
 
 [package.metadata.release]
+# Instruct `cargo release` to not run `cargo publish` locally:
+# https://github.com/sunng87/cargo-release/blob/master/docs/reference.md#config-fields
+# See docs/releasing.md for details.
 disable-publish = true

docs/releasing.md

@@ -1,6 +1,9 @@
 # Releasing
 
-Releasing, i.e. crate publishing, has been automated via GitHub Actions.
+## Prerequisites
+Publishing to crates.io has been automated via GitHub Actions, so you will only
+need push access to the [ballista-compute GitHub repository](https://github.com/ballista-compute/sqlparser-rs)
+in order to publish a release.
 
 We use the [`cargo release`](https://github.com/sunng87/cargo-release)
 subcommand to ensure correct versioning. Install via:
@@ -9,29 +12,47 @@ subcommand to ensure correct versioning. Install via:
 $ cargo install cargo-release
 ```
 
-**Before releasing** ensure `CHANGELOG.md` is updated appropriately.
-
 ## Process
 
-Using `cargo-release` we can author a new minor release like so:
+1. **Before releasing** ensure `CHANGELOG.md` is updated appropriately and that
+    you have a clean checkout of the `main` branch of the sqlparser repository:
+    ```
+    $ git fetch && git status
+    On branch main
+    Your branch is up to date with 'upstream/main'.
 
-```
-$ cargo release minor --skip-publish
-```
+    nothing to commit, working tree clean
+    ```
+    * If you have the time, check that the examples in the README are up to date.
 
-**Ensure publishing is skipped** since pushing the resulting tag upstream will
-handle crate publishing automatically.
+2. Using `cargo-release` we can publish a new release like so:
 
-This will create a new tag, `0.6.0` with the message,
-`(cargo-release) sqlparser version 0.6.0`.
+    ```
+    $ cargo release minor --push-remote upstream
+    ```
 
-Once the tag is created, pushing the tag upstream will trigger a publishing
-process to crates.io. Now to push our example tag:
+    You can add `--dry-run` to see what the command is going to do,
+    or `--skip-push` to stop before actually publishing the release.
 
-```
-git push origin 0.6.0
-```
+    `cargo release` will then:
+
+    * Bump the minor part of the version in `Cargo.toml` (e.g. `0.7.1-alpha.0`
+       -> `0.8.0`. You can use `patch` instead of `minor`, as appropriate).
+    * Create a new tag (e.g. `v0.8.0`) locally
+    * Push the new tag to the specified remote (`upstream` in the above
+      example), which will trigger a publishing process to crates.io as part of
+      the [corresponding GitHub Action](https://github.com/ballista-compute/sqlparser-rs/blob/main/.github/workflows/rust.yml).
+
+      Note that credentials for authoring in this way are securely stored in
+      the (GitHub) repo secrets as `CRATE_TOKEN`.
+    * Bump the crate version again (to something like `0.8.1-alpha.0`) to
+      indicate the start of new development cycle.
+
+3. Push the updates to the `main` branch upstream:
+    ```
+    $ git push upstream
+    ```
+
+4. Check that the new version of the crate is available on crates.io:
+    https://crates.io/crates/sqlparser
 
-(Note that this process is fully automated; credentials
-for authoring in this way are securely stored in the repo secrets as
-`CRATE_TOKEN`.)