From 88f680258477471741fa3a9c392f445c0a88fc58 Mon Sep 17 00:00:00 2001
From: Cark <carkhy@gmail.com>
Date: Tue, 20 Feb 2018 11:52:47 +0100
Subject: [PATCH] Added "Dev Workflow" to "Advanced" docs

Closes #69

Signed-off-by: Cark <carkhy@gmail.com>
---
 doc/SUMMARY.md               |   1 +
 doc/advanced/dev_workflow.md | 149 +++++++++++++++++++++++++++++++++++
 2 files changed, 150 insertions(+)
 create mode 100644 doc/advanced/dev_workflow.md

diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md
index 9b53c29a..aec6ecfd 100644
--- a/doc/SUMMARY.md
+++ b/doc/SUMMARY.md
@@ -18,6 +18,7 @@
     * [Configuring Routers](advanced/configuring_routers.md)
     * [Different Routers](advanced/different_routers.md)
     * [Route Validation](advanced/route_validation.md)
+    * [Dev Workflow](advanced/dev_workflow.md)
 * [Ring](ring/README.md)
     * [Ring-router](ring/ring.md)
     * [Dynamic Extensions](ring/dynamic_extensions.md)
diff --git a/doc/advanced/dev_workflow.md b/doc/advanced/dev_workflow.md
new file mode 100644
index 00000000..b84c5ddd
--- /dev/null
+++ b/doc/advanced/dev_workflow.md
@@ -0,0 +1,149 @@
+# Dev Worklfow
+
+Many applications will require the routes to span multiple namespaces. It is quite easy to do so with reitit, but we might hit a problem during developement.
+
+## An example
+
+Consider this sample routing :
+
+```clj
+(ns ns1)
+
+(def routes
+  ["/bar" ::bar])
+
+(ns ns2)
+(require '[ns1])
+
+(def routes
+  [["/ping" ::ping]
+   ["/more" ns1/routes]])
+
+(ns ns3)
+(require '[ns1])
+(require '[ns2])
+(require '[reitit.core :as r])
+
+(def routes
+  ["/api"
+   ["/ns2" ns2/routes]
+   ["/ping" ::ping]])
+
+(def router (r/router routes))
+```
+
+We may query the top router and get the expected result :
+```clj
+(r/match-by-path router "/api/ns2/more/bar")
+;#reitit.core.Match{:template "/api/ns2/more/bar", :data {:name :ns1/bar}, :result nil, :path-params {}, :path "/api/ns2/more/bar"}
+```
+
+Notice the route name : ```:ns1/bar```
+
+When we change the routes in ```ns1``` like this :
+```clj
+(ns ns1
+  (:require [reitit.core :as r]))
+  
+(def routes
+  ["/bar" ::bar-with-new-name])
+```
+
+After we recompile the ```ns1``` namespace, and query again
+```clj
+ns1/routes
+;["/bar" :ns1/bar-with-new-name]
+;The routes var in ns1 was changed indeed
+
+(r/match-by-path router "/api/ns2/more/bar")
+;#reitit.core.Match{:template "/api/ns2/more/bar", :data {:name :ns1/bar}, :result nil, :path-params {}, :path "/api/ns2/more/bar"}
+```
+
+The route name is still ```:ns1/bar``` !
+
+While we could use the [reloaded workflow](http://thinkrelevance.com/blog/2013/06/04/clojure-workflow-reloaded) to reload the whole routing tree, it is not always possible, and quite frankly a bit slower than we might want for fast iterations.
+
+## A crude solution
+
+In order to see the changes without reloading the whole route tree, we can use functions.
+
+```clj
+(ns ns1)
+
+(defn routes [] ;; Now a function !
+  ["/bar" ::bar])
+
+(ns ns2)
+(require '[ns1])
+
+(defn routes [] ;; Now a function !
+  [["/ping" ::ping]
+   ["/more" (ns1/routes)]]) ;; Now a function call
+
+(ns ns3)
+(require '[ns1])
+(require '[ns2])
+(require '[reitit.core :as r])
+
+(defn routes [] ;; Now a function !
+  ["/api"
+   ["/ns2" (ns2/routes)] ;; Now a function call
+   ["/ping" ::ping]])
+
+(def router #(r/router (routes))) ;; Now a function
+```
+
+Let's query again
+
+```clj
+(r/match-by-path (router) "/api/ns2/more/bar") 
+;#reitit.core.Match{:template "/api/ns2/more/bar", :data {:name :ns1/bar}, :result nil, :path-params {}, :path "/api/ns2/more/bar"}
+```
+
+Notice that's we're now calling a function rather than just passing ```router``` to the matching function.
+
+Now let's again change the route name in ```ns1```, and recompile that namespace.
+
+```clj
+(ns ns1)
+
+(defn routes [] 
+  ["/bar" ::bar-with-new-name])
+```
+
+let's see the query result :
+
+```clj
+(r/match-by-path (router) "/api/ns2/more/bar")
+;#reitit.core.Match{:template "/api/ns2/more/bar", :data {:name :ns1/bar-with-new-name}, :result nil, :path-params {}, :path "/api/ns2/more/bar"}
+```
+
+Notice that the name is now correct, without reloading every namespace under the sun.
+
+## Why is this a crude solution ?
+
+The astute reader will have noticed that we're recompiling the full routing tree on every invocation. While this solution is practical during developement, it goes contrary to the performance goals of reitit. 
+
+We need a way to only do this once at production time.
+
+## An easy fix
+
+Let's apply a small change to our ```ns3```. We'll replace our router by two different routers, one for dev and one for production.
+
+```clj
+(ns ns3)
+(require '[ns1])
+(require '[ns2])
+(require '[reitit.core :as r])
+
+(defn routes [] 
+  ["/api"
+   ["/ns2" (ns2/routes)] 
+   ["/ping" ::ping]])
+
+(def dev-router #(r/router (routes))) ;; A router for dev
+(def prod-router (constantly (r/router (routes)))) ;; A router for prod 
+```
+
+And there you have it, dynamic during dev, performance at production. We have it all !
+