From 041e51742250c0760d15df6042895d2182812df0 Mon Sep 17 00:00:00 2001
From: Marc Garreau <3621728+marcgarreau@users.noreply.github.com>
Date: Fri, 18 Jun 2021 14:13:39 -0600
Subject: [PATCH] support unreleased Geth builds in CI

---
 .circleci/config.yml       | 39 ++++++++++++++++++++++++++++++++++++++
 docs/contributing.rst      | 26 +++++++++++++++++++++++++
 newsfragments/2037.doc.rst |  1 +
 3 files changed, 66 insertions(+)
 create mode 100644 newsfragments/2037.doc.rst

diff --git a/.circleci/config.yml b/.circleci/config.yml
index dad25f6b35..2cc282a20c 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -110,6 +110,45 @@ geth_steps: &geth_steps
           - ~/.py-geth
         key: cache-{{ .Environment.CIRCLE_JOB }}-{{ checksum "setup.py" }}-{{ checksum "tox.ini" }}
 
+geth_custom_steps: &geth_custom_steps
+  working_directory: ~/repo
+  steps:
+    - checkout
+    - restore_cache:
+        keys:
+          - cache-{{ .Environment.CIRCLE_JOB }}-{{ checksum "setup.py" }}-{{ checksum "tox.ini" }}
+    - run:
+        name: install dependencies
+        command: pip install --user tox
+    - run:
+        name: use a pre-built geth binary
+        command: |
+          mkdir -p $HOME/.ethash
+          export GOROOT=/usr/local/go
+          echo $GETH_VERSION
+          export GETH_BINARY="./custom_geth"
+          echo 'export GETH_BINARY="./custom_geth"' >> $BASH_ENV
+          curl -O https://storage.googleapis.com/golang/go1.14.2.linux-amd64.tar.gz
+          tar xvf go1.14.2.linux-amd64.tar.gz
+          sudo chown -R root:root ./go
+          sudo mv go /usr/local
+          sudo ln -s /usr/local/go/bin/go /usr/local/bin/go
+          sudo apt-get update;
+          sudo apt-get install -y build-essential;
+          ./custom_geth version
+          ./custom_geth makedag 0 $HOME/.ethash
+    - run:
+        name: run tox
+        command: ~/.local/bin/tox -r
+    - save_cache:
+        paths:
+          - .tox
+          - ~/.cache/pip
+          - ~/.local
+          - ./eggs
+          - ~/.ethash
+        key: cache-{{ .Environment.CIRCLE_JOB }}-{{ checksum "setup.py" }}-{{ checksum "tox.ini" }}
+
 ethpm_steps: &ethpm_steps
   working_directory: ~/repo
   steps:
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 8ccbf175f0..4a365c2c4d 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -265,6 +265,32 @@ Geth fixtures
    you may again include the ``GETH_BINARY`` environment variable.
 
 
+CI testing with a nightly Geth build
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Occasionally you'll want to have CI run the test suite against an unreleased version of Geth,
+for example, to test upcoming hard fork changes. The workflow described below is for testing only,
+i.e., open a PR, let CI run the tests, but the changes should only be merged into master once the
+Geth release is published or you have some workaround that doesn't require test fixtures built from
+an unstable client.
+
+1. Configure ``tests/integration/generate_fixtures/go_ethereum/common.py`` as needed.
+
+2. Geth automagically compiles new builds for every commit that gets merged into the codebase.
+   Download the desired build from the `develop builds <https://geth.ethereum.org/downloads/>`_.
+
+3. Build your test fixture, passing in the binary you just downloaded via ``GETH_BINARY``. Don't forget
+   to update the ``/tests/integration/go_ethereum/conftest.py`` file to point to your new fixture.
+
+4. Our CI runs on Ubuntu, so download the corresponding 64-bit Linux
+   `develop build <https://geth.ethereum.org/downloads/>`_, then
+   add it to the root of your Web3.py directory. Rename the binary ``custom_geth``.
+
+5. In ``.circleci/config.yml``, update jobs relying on ``geth_steps``, to instead use ``custom_geth_steps``.
+
+6. Create a PR and let CI do its thing.
+
+
 Parity/OpenEthereum fixtures
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/newsfragments/2037.doc.rst b/newsfragments/2037.doc.rst
new file mode 100644
index 0000000000..f8d4b7f017
--- /dev/null
+++ b/newsfragments/2037.doc.rst
@@ -0,0 +1 @@
+Detail using unreleased Geth builds in CI