From 7d5be3e5daccdac13491798552c3e8eb3add7eb1 Mon Sep 17 00:00:00 2001
From: Sam Kleinman <garen@tychoish.com>
Date: Fri, 4 Feb 2022 17:02:45 -0500
Subject: [PATCH] adr: merge tendermint/spec repository into
 tendermint/tendermint (#7775)

---
 docs/architecture/README.md                   |   2 +
 .../architecture/adr-076-combine-spec-repo.md | 112 ++++++++++++++++++
 2 files changed, 114 insertions(+)
 create mode 100644 docs/architecture/adr-076-combine-spec-repo.md

diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 6e2dd6a1c..b6625cc80 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -80,6 +80,7 @@ Note the context/background should be written in the present tense.
 - [ADR-068: Reverse-Sync](./adr-068-reverse-sync.md)
 - [ADR-067: Mempool Refactor](./adr-067-mempool-refactor.md)
 - [ADR-075: RPC Event Subscription Interface](./adr-075-rpc-subscription.md)
+- [ADR-076: Combine Spec and Tendermint Repositories](./adr-076-combine-spec-repo.md)
 
 ### Rejected
 
@@ -103,3 +104,4 @@ Note the context/background should be written in the present tense.
 - [ADR-069: Node Initialization](./adr-069-flexible-node-initialization.md)
 - [ADR-071: Proposer-Based Timestamps](adr-071-proposer-based-timestamps.md)
 - [ADR-074: Migrate Timeout Parameters to Consensus Parameters](./adr-074-timeout-params.md)
+
diff --git a/docs/architecture/adr-076-combine-spec-repo.md b/docs/architecture/adr-076-combine-spec-repo.md
new file mode 100644
index 000000000..a6365da5b
--- /dev/null
+++ b/docs/architecture/adr-076-combine-spec-repo.md
@@ -0,0 +1,112 @@
+# ADR 076: Combine Spec and Tendermint Repositories 
+
+## Changelog
+
+- 2022-02-04: Initial Draft. (@tychoish)
+
+## Status
+
+Accepted.
+
+## Context
+
+While the specification for Tendermint was originally in the same
+repository as the Go implementation, at some point the specification
+was split from the core repository and maintained separately from the
+implementation. While this makes sense in promoting a conceptual
+separation of specification and implementation, in practice this
+separation was a premature optimization, apparently aimed at supporting
+alternate implementations of Tendermint. 
+
+The operational and documentary burden of maintaining a separate
+spec repo has not returned value to justify its cost. There are no active
+projects to develop alternate implementations of Tendermint based on the
+common specification, and having separate repositories creates an ongoing
+burden to coordinate versions, documentation, and releases.
+
+## Decision
+
+The specification repository will be merged back into the Tendermint
+core repository.
+
+Stakeholders including representatives from the maintainers of the
+spec, the Go implementation, and the Tendermint Rust library, agreed
+to merge the repositories in the Tendermint core dev meeting on 27
+January 2022, including @williambanfield @cmwaters @creachadair and
+@thanethomson.
+
+## Alternative Approaches
+
+The main alternative we considered was to keep separate repositories,
+and to introduce a coordinated versioning scheme between the two, so
+that users could figure out which spec versions go with which versions
+of the core implementation.
+
+We decided against this on the grounds that it would further complicate
+the release process for _both_ repositories, without mitigating any of
+the other existing issues.
+
+## Detailed Design
+
+Clone and merge the master branch of the `tendermint/spec` repository
+as a branch of the `tendermint/tendermint`, to ensure the commit history
+of both repositories remains intact.
+
+### Implementation Instructions
+
+1. Within the `tendermint` repository, execute the following commands 
+   to add a new branch with the history of the master branch of `spec`:
+
+   ```bash
+   git remote add spec git@github.com:tendermint/spec.git
+   git fetch spec
+   git checkout -b spec-master spec/master
+   mkdir spec
+	git ls-tree -z --name-only HEAD | xargs -0 -I {} git mv {} subdir/
+	git commit -m "spec: organize specification prior to merge"
+	git checkout -b spec-merge-mainline origin/master
+	git merge --allow-unrelated-histories spec-master
+	```
+
+   This merges the spec into the `tendermint/tendermint` repository as
+   a normal branch. This commit can also be backported to the 0.35
+   branch, if needed.
+
+2. Migrate outstanding issues from `tendermint/spec` to the
+   `tendermint/tendermint` repository.
+
+3. In the specification repository, add redirect to the README and mark
+   the repository as archived. 
+   
+
+## Consequences
+
+### Positive
+
+Easier maintenance for the specification will obviate a number of
+complicated and annoying versioning problems, and will help prevent the
+possibility of the specification and the implementation drifting apart.
+
+Additionally, co-locating the specification will help encourage
+cross-pollination and collaboration, between engineers focusing on the
+specification and the protocol and engineers focusing on the implementation.
+
+### Negative
+
+Co-locating the spec and Go implementation has the potential effect of
+prioritizing the Go implementation with regards to the spec, and
+making it difficult to think about alternate implementations of the
+Tendermint algorithm. Although we may want to foster additional
+Tendermint implementations in the future, this isn't an active goal
+in our current roadmap, and *not* merging these repos doesn't
+change the fact that the Go implementation of Tendermint is already the
+primary implementation.
+
+### Neutral
+
+N/A
+
+## References
+
+- https://github.com/tendermint/spec
+- https://github.com/tendermint/tendermint