Merge pull request #129 from nathan-at-least/release-process

Release process.

README.md

@@ -1,6 +1,8 @@
 # tfl-book
 
-This repository is an `mdbook` instance for a `Trailing Finality Layer` design for Zcash.
+The [Zcash Trailing Finality Layer](https://electric-coin-company.github.io/tfl-book/) design book.
+
+This repository is the source text and rendering configuration for the book. To read the book, use the link above.
 
 The `mdbook` tool renders the contents into a pretty format from `markdown` based source code
 
@@ -37,3 +39,41 @@ git config --local core.hooksPath git-hooks
 ## Rendering
 
 - `mdbook build`
+
+## Release Process
+
+Releases are defined as distinct revisions that embody a consistent set of changes from the prior releases, identified by a version with `XXX.YYY.ZZZ` format. Releases serve a few purposes. They:
+
+- ensure that readers can better notice changes or updates between readings or in discussions with others,
+- signify that the authors have converged after a period of editing onto a coherent integrated result,
+- signify an approximate maturity of the design, based on the version number, and
+- serve as a natural milestone for announcements on design updates.
+
+### Versioning Schema
+
+The versioning scheme isn't precise and roughly follows this rubrik:
+
+When a version `X.Y.Z` increments, the scope of change since the prior release is implied by the new version:
+
+- `<X+1>.0.0` - This release represents a complete, well analyzed design which the authors believe could be a suitable candidate for Zcash (or other crypto networks) to productionize by developing conforming implementations that activate in production.
+- `X.<Y+1>.0` - This release introduces or changes substantial design decisions or analyses, or it changes the presentation (such as the order or content of chapters) significantly. A reader of only the prior release may be missing essential details in understanding this new release.
+- `X.Y.<Z+1>` - This release improves the wording, layout, rendering, or other content in a manner that doesn't rise to the threshold of the previous case.
+
+### Release Process
+
+To create a new release:
+
+1. Decide that the `main` branch is in a coherent state without likely sources of confusion or self-inconsistency.
+2. Decide the new release's version as in [Versioning Schema](#versioning-schema) above.
+3. Create a release branch named `release-<NEW VERSION>`.
+4. Update the release branch with these changes:
+  - `book.toml`: Modify the `title` to end with `vX.Y.Z`. This ensures the version is visible to readers on all pages.
+  - `src/version-history.md`: Introduce a new heading `## X.Y.Z - <RELEASE TITLE>` above all prior entries (i.e. reverse chronologically).
+    - The `RELEASE TITLE` should be a short-hand title capturing the primary change of the release.
+    - The release body should always begin with a link titled `Issue Tracking` that navigates to the GitHub milestone page of completed issues in this release.
+    - The rest of the release body should be a one- to three-sentence summary of changes. Readers who need more detail can follow issue tracking.
+  - `src/introduction.md`: The first paragraph says `This is <VERSION LINK> of the book.` Update that link to point to the new release's entry in `src/version-history.md`.
+5. Submit those changes for GitHub pull-request review, resolve any blocking concerns, then merge to the `main` branch. Note: This step will render the release.
+6. Create a git tag on the git commit that merges into `main`: `git tag vX.Y.Z && git push --tags`
+
+Note: We don't use GitHub "releases" since there's no release artifact other than the already published rendering.

book.toml

@@ -3,7 +3,7 @@ authors = ["Nate Wilcox"]
 language = "en"
 multilingual = false
 src = "src"
-title = "Zcash Trailing Finality Layer"
+title = "Zcash Trailing Finality Layer - v0.0.0"
 
 [build]
 # When there is more than one [output.*] section, the HTML will be generated under `<build-dir>/html/`.

src/SUMMARY.md

@@ -25,3 +25,4 @@
     - [Network Architecture Analysis]()
   - [Concrete Analysis]()
 - [References](./references.md)
+- [Version History](./version-history.md)

src/introduction.md

@@ -1,6 +1,6 @@
 # A Trailing Finality Layer for Zcash
 
-This book introduces and specifies a [*Trailing Finality Layer*](./terminology.md#definition-tfl) for the Zcash network.
+This book introduces and specifies a [*Trailing Finality Layer*](./terminology.md#definition-tfl) for the Zcash network. (**TODO:** Add a sentence describing the version linked in the latest [Version History](./version-history.md) entry.)
 
 This design augments the existing Zcash Proof-of-Work ([PoW](./terminology.md#definition-pow)) network with a new consensus layer which provides [*trailing finality*](./terminology.md#definition-trailing-finality). This layer enables transactions included via PoW to become [*final*](./terminology.md#definition-final) which assures that they cannot be reverted by the protocol. This enables safer and simpler wallets and other infrastructure, and aids trust-minimized cross-chain bridges. This consensus layer uses [*Proof-of-Stake*](./terminology.md#definition-pos) consensus, and enables ZEC holders to earn protocol rewards for contributing to the security of the Zcash network. By integrating a PoS layer with the current PoW Zcash protocol, this design specifies a [*hybrid consensus*](./terminology.md#definition-hybrid-consensus) protocol dubbed [PoW+TFL](./terminology.md#definition-pow-tfl).
 

src/version-history.md

@@ -0,0 +1,5 @@
+# Version History
+
+## Prehistory - Zcon4 Presentation
+
+Prior to the initial release of this book, a design sketch was presented in [Interactive Design of a Zcash Trailing Finality Layer (Hybrid PoW+PoS) by Nate Wilcox: Zcon4](https://www.youtube.com/watch?v=qhMzMYeEPMM&list=PL40dyJ0UYTLII7oQRQmNOFf0d2iKT35tL&index=19).