From 795d40a0034457afe83e7dd277be211120abff2b Mon Sep 17 00:00:00 2001
From: teor <teor@riseup.net>
Date: Tue, 20 Jun 2023 17:10:40 +1000
Subject: [PATCH] change(readme): Install from crates.io not git in the README,
 automate release version replacements (#6977)

* Install from crates.io not git

* Move git instructions to install.md

* Add versions back to install.md

* Automate release replacements in Cargo.toml

* Re-add h4 to re-enable links to those sections

* Remove release replacements from zebra/Cargo.toml

* Add release replacements to zebrad/Cargo.toml

* Put the toml table in the right place

* Try another place in Cargo.toml

* Let's try again without "package."

* Remove duplicate release metadata from Cargo.toml

* Apply suggestions from code review

Co-authored-by: Marek <mail@marek.onl>

---------

Co-authored-by: Marek <mail@marek.onl>
---
 Cargo.toml               |  2 ++
 README.md                | 16 ++++++----
 book/src/user/install.md | 66 +++++++++++++++++++++++++++++-----------
 zebrad/Cargo.toml        | 20 ++++++++----
 4 files changed, 74 insertions(+), 30 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index e6ffaefb9..0f81f34fa 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -17,6 +17,8 @@ members = [
 # Use the edition 2021 dependency resolver in the workspace, to match the crates
 resolver = "2"
 
+# Compilation settings
+
 [profile.dev]
 panic = "abort"
 
diff --git a/README.md b/README.md
index 9c4ae1886..af14b07cd 100644
--- a/README.md
+++ b/README.md
@@ -74,7 +74,9 @@ Every few weeks, we release a [new Zebra version](https://github.com/ZcashFounda
 
 Below are quick summaries for installing the dependencies on your machine.
 
-<details><summary><h4>General instructions for installing dependencies</h4></summary>
+<details>
+
+<summary><h4>General instructions for installing dependencies</h4></summary>
 
 1. Install [`cargo` and `rustc`](https://www.rust-lang.org/tools/install).
 
@@ -88,7 +90,9 @@ Below are quick summaries for installing the dependencies on your machine.
 
 </details>
 
-<details><summary><h4>Dependencies on Arch</h4></summary>
+<details>
+
+<summary><h4>Dependencies on Arch</h4></summary>
 
 ```sh
 sudo pacman -S rust clang pkgconf
@@ -98,10 +102,10 @@ Note that the package `clang` includes `libclang` as well as the C++ compiler.
 
 </details>
 
-Once the dependencies are in place, you can build Zebra
+Once the dependencies are in place, you can build and install Zebra:
 
 ```sh
-cargo install --locked --git https://github.com/ZcashFoundation/zebra --tag v1.0.0 zebrad
+cargo install --locked zebrad
 ```
 
 You can start Zebra by
@@ -110,8 +114,8 @@ You can start Zebra by
 zebrad start
 ```
 
-See the [Running Zebra](https://zebra.zfnd.org/user/run.html) section in the
-book for more details.
+See the [Installing Zebra](https://zebra.zfnd.org/user/install.html) and [Running Zebra](https://zebra.zfnd.org/user/run.html)
+sections in the book for more details.
 
 #### Optional Features
 
diff --git a/book/src/user/install.md b/book/src/user/install.md
index 9f9826f64..c93790920 100644
--- a/book/src/user/install.md
+++ b/book/src/user/install.md
@@ -2,19 +2,64 @@
 
 Follow the [Docker or compilation instructions](https://zebra.zfnd.org/index.html#getting-started).
 
-#### ARM
+## Installing Dependencies
+
+To compile Zebra from source, you will need to [install some dependencies.](https://zebra.zfnd.org/index.html#building-zebra).
+
+
+## Alternative Compilation Methods
+
+### Compiling Manually from git
+
+To compile Zebra directly from GitHub, or from a GitHub release source archive:
+
+1. Install the dependencies (see above)
+
+2. Get the source code using `git` or from a GitHub source package
+
+```sh
+git clone https://github.com/ZcashFoundation/zebra.git
+cd zebra
+git checkout v1.0.0
+```
+
+3. Build and Run `zebrad`
+
+```sh
+cargo build --release --bin zebrad
+target/release/zebrad start
+```
+
+### Compiling from git using cargo install
+
+```sh
+cargo install --git https://github.com/ZcashFoundation/zebra --tag v1.0.0 zebrad
+```
+
+### Compiling on ARM
 
 If you're using an ARM machine, [install the Rust compiler for
 ARM](https://rust-lang.github.io/rustup/installation/other.html). If you build
 using the x86_64 tools, Zebra might run really slowly.
 
-#### Build Troubleshooting
+## Build Troubleshooting
 
 If you're having trouble with:
 
-Dependencies:
+### Compilers
+
+- **clang:** install both `libclang` and `clang` - they are usually different packages
+- **libclang:** check out the [clang-sys documentation](https://github.com/KyleMayes/clang-sys#dependencies)
+- **g++ or MSVC++:** try using clang or Xcode instead
+- **rustc:** use the latest stable `rustc` and `cargo` versions
+  - Zebra does not have a minimum supported Rust version (MSRV) policy: any release can update the required Rust version.
+
+### Dependencies
 
 - use `cargo install` without `--locked` to build with the latest versions of each dependency
+
+#### Optional Tor feature
+
 - **sqlite linker errors:** libsqlite3 is an optional dependency of the `zebra-network/tor` feature.
   If you don't have it installed, you might see errors like `note: /usr/bin/ld: cannot find -lsqlite3`.
   [Follow the arti instructions](https://gitlab.torproject.org/tpo/core/arti/-/blob/main/CONTRIBUTING.md#setting-up-your-development-environment)
@@ -25,19 +70,4 @@ cargo build
 cargo build -p zebrad --all-features
 ```
 
-Compilers:
 
-- **clang:** install both `libclang` and `clang` - they are usually different packages
-- **libclang:** check out the [clang-sys documentation](https://github.com/KyleMayes/clang-sys#dependencies)
-- **g++ or MSVC++:** try using clang or Xcode instead
-- **rustc:** use rustc 1.65 or later
-  - Zebra does not have a minimum supported Rust version (MSRV) policy: any release can update the required Rust version.
-
-### Dependencies
-
-Zebra primarily depends on pure Rust crates, and some Rust/C++ crates:
-
-- [rocksdb](https://crates.io/crates/rocksdb)
-- [zcash_script](https://crates.io/crates/zcash_script)
-
-They will be automatically built along with `zebrad`.
diff --git a/zebrad/Cargo.toml b/zebrad/Cargo.toml
index 7b65394c3..9fb96712c 100644
--- a/zebrad/Cargo.toml
+++ b/zebrad/Cargo.toml
@@ -7,6 +7,13 @@ description = "The Zcash Foundation's independent, consensus-compatible implemen
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/ZcashFoundation/zebra"
 
+readme = "../README.md"
+homepage = "https://zfnd.org/zebra/"
+# crates.io is limited to 5 keywords and categories
+keywords = ["zebra", "zcash"]
+# Must be one of <https://crates.io/category_slugs>
+categories = ["command-line-utilities", "cryptography::cryptocurrencies"]
+
 # Settings that impact compilation
 edition = "2021"
 
@@ -20,12 +27,13 @@ rust-version = "1.66"
 # when run in the workspace directory
 default-run = "zebrad"
 
-readme = "../README.md"
-homepage = "https://zfnd.org/zebra/"
-# crates.io is limited to 5 keywords and categories
-keywords = ["zebra", "zcash"]
-# Must be one of <https://crates.io/category_slugs>
-categories = ["command-line-utilities", "cryptography::cryptocurrencies"]
+# `cargo release` settings
+[metadata.release]
+pre-release-replacements = [
+  {file="../book/src/user/install.md", search="git checkout [a-z0-9\\.-]+", replace="git checkout {{version}}"},
+  {file="../book/src/user/install.md", search="--tag [a-z0-9\\.-]+", replace="--tag {{version}}"},
+  {file="../book/src/user/docker.md", search="--branch [a-z0-9\\.-]+", replace="--branch {{version}}"},
+]
 
 [features]
 # In release builds, don't compile debug logging code, to improve performance.