From 484844aa1addc7316b7f6c03b6a494ec0ba674bc Mon Sep 17 00:00:00 2001
From: Alexander Neumann <alexander@bumpern.de>
Date: Sat, 13 Oct 2018 12:53:01 +0200
Subject: [PATCH] Document the build and release processes

---
 .gitignore                    |  1 -
 doc/.gitignore                |  2 +
 doc/Makefile                  |  7 +++-
 doc/developer_information.rst | 78 ++++++++++++++++++++++++++++++++---
 4 files changed, 81 insertions(+), 7 deletions(-)
 create mode 100644 doc/.gitignore

diff --git a/.gitignore b/.gitignore
index ae7849d51..33a01ba61 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,2 @@
 /restic
 /.vagrant
-/doc/_build
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 000000000..849362b48
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1,2 @@
+_build
+.doctrees
diff --git a/doc/Makefile b/doc/Makefile
index 96ccd045b..a296c0742 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -17,4 +17,9 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: autobuild
+
+autobuild:
+	sphinx-autobuild -b html -i '.doctrees/*' . _build
diff --git a/doc/developer_information.rst b/doc/developer_information.rst
index c1ee8a174..f962863e7 100644
--- a/doc/developer_information.rst
+++ b/doc/developer_information.rst
@@ -28,16 +28,16 @@ In the following example, we'll use the file ``restic-0.9.3.tar.gz`` and Go
 
 .. code::
 
-    # cd /usr/local
-    # curl -L https://dl.google.com/go/go1.11.1.linux-amd64.tar.gz | tar xz
+    $ cd /usr/local
+    $ curl -L https://dl.google.com/go/go1.11.1.linux-amd64.tar.gz | tar xz
 
 2. Extract the restic source code into ``/restic``
 
 .. code::
 
-    # mkdir /restic
-    # cd /restic
-    # TZ=Europe/Berlin curl -L https://github.com/restic/restic/releases/download/v0.9.3/restic-0.9.3.tar.gz | tar xz --strip-components=1
+    $ mkdir /restic
+    $ cd /restic
+    $ TZ=Europe/Berlin curl -L https://github.com/restic/restic/releases/download/v0.9.3/restic-0.9.3.tar.gz | tar xz --strip-components=1
 
 3. Build the binaries for Windows and Linux:
 
@@ -53,3 +53,71 @@ In the following example, we'll use the file ``restic-0.9.3.tar.gz`` and Go
     $ GOOS=windows GOARCH=amd64 CGO_ENABLED=0 go build -mod=vendor -ldflags "-s -w" -tags selfupdate -o restic_windows_amd64.exe ./cmd/restic
     $ touch --reference VERSION restic_windows_amd64.exe
     $ TZ=Europe/Berlin zip -q -X restic_windows_amd64.zip restic_windows_amd64.exe
+
+Building the Official Binaries
+******************************
+
+The released binaries for restic are built using a Docker container. You can
+find it on `Docker Hub <https://hub.docker.com/r/restic/builder>`__ as
+``restic/builder``, the ``Dockerfile`` and instructions on how to build the
+container can be found in the `GitHub repository
+<https://github.com/restic/builder>`__
+
+The container serves the following goals:
+ * Have a very controlled environment which is independent from the local system
+ * Make it easy to have the correct version of the Go compiler at the right path
+ * Make it easy to pass in the source code to build at a well-defined path
+
+The following steps are necessary to build the binaries:
+
+1. Either build the container (see the instructions in the `repository's README <https://github.com/restic/builder>`__). Alternatively, download the container from the hub:
+
+.. code::
+
+    docker pull restic/builder
+
+2. Extract the source code somewhere:
+
+.. code::
+
+    tar xvzf restic-0.9.3.tar.gz
+
+3. Create a directory to place the resulting binaries in:
+
+.. code::
+
+    mkdir output
+
+3. Mount the source code and the output directory in the container and run the default command, which starts ``helpers/build-release-binaries/main.go``:
+
+.. code::
+
+    docker run --rm \
+        --volume "$PWD/restic-0.9.3:/restic" \
+        --volume "$PWD/output:/output" \
+        restic/builder
+
+4. If anything goes wrong, you can enable debug output by specifying the call to ``helpers/build-release-binaries/main.go`` like this:
+
+.. code::
+
+    docker run --rm \
+        --volume "$PWD/restic-0.9.3:/restic" \
+        --volume "$PWD/output:/output" \
+        restic/builder \
+        go run -mod=vendor helpers/build-release-binaries/main.go --verbose
+
+Prepare a New Release
+*********************
+
+Publishing a new release of restic requires many different steps. We've
+automated this in the Go program ``helpers/prepare-release/main.go`` which also
+includes checking that e.g. the changelog is correctly generated. The only
+required argument is the new version number (in `Semantic Versioning
+<https://semver.org/>`__ format ``MAJOR.MINOR.PATCH``):
+
+.. code::
+
+    go run -mod=vendor helpers/prepare-release/main.go 0.9.3
+
+Checks can be skipped on demand via flags, please see ``--help`` for details.