From 45ac8e0cbc1c8a21c6b942ab665513c5e043ccb5 Mon Sep 17 00:00:00 2001
From: Tobias Pflug <tobias.pflug@gmail.com>
Date: Thu, 14 May 2020 12:53:01 +0200
Subject: [PATCH] README.md: info about runHydra/foreman

Add sections about using `runHydra` and `foreman`
---
 README.md | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/README.md b/README.md
index c4a40de9..113254b7 100644
--- a/README.md
+++ b/README.md
@@ -70,6 +70,7 @@ Make sure **State** at the top of the page is set to "_Enabled_" and click on "_
 ### Building Hydra
 
 You can build Hydra via `nix-build` using the provided [default.nix](./default.nix):
+
 ```
 $ nix-build
 ```
@@ -84,6 +85,44 @@ $ configurePhase # NOTE: not ./configure
 $ make
 ```
 
+### Development Workflow
+
+When working on new features or bug fixes you want to be able to run Hydra from your working copy. There are
+two ways to do this. One is better for interactive development and provides faster feedback cycles, the other
+is more convenient for a single test run of Hydra from the working copy (suiteable for PR reviews).
+
+#### Using runHydra
+
+Hydra can be built and executed using the `runHydra` shell:
+
+```
+$ nix-shell default.nix -A runHydra
+```
+
+This will spawn a shell that starts hydra-server, hydra-queue-runner, hydra-evaluator and postgres using [foreman](https://github.com/ddollar/foreman).
+In order to not collide with potentially existing installations running on default ports hydra and postgres are running on custom ports:
+
+- hydra-server: 63333
+- postgresql: 64444
+
+**Note**: In some cases you may want to skip test execution. You can do so by passing `doCheck false`:
+
+```
+$ nix-shell default.nix -A runHydra --arg doCheck false
+```
+
+#### Using foreman
+
+When you are actively working on the code, you need fast feedback cycles and thus want incremental builds. Instead of using
+`runHydra` you can just run `foreman start` directly in the normal `nix-shell` environment:
+
+```
+$ nix-shell
+$ # hack hack
+$ make
+$ foreman start
+```
+
 ### JSON API
 
 You can also interface with Hydra through a JSON API. The API is defined in [hydra-api.yaml](./hydra-api.yaml) and you can test and explore via the [swagger editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/NixOS/hydra/master/hydra-api.yaml)