From 93f66d6bc515e9a7e6ddb097a1ace88f8427c895 Mon Sep 17 00:00:00 2001 From: Daniel Compton Date: Wed, 14 Feb 2018 21:29:08 +1300 Subject: [PATCH 01/22] Version 0.1.22-SNAPSHOT --- project.clj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project.clj b/project.clj index f0b08ee..80334b2 100644 --- a/project.clj +++ b/project.clj @@ -1,4 +1,4 @@ -(defproject day8.re-frame/trace "0.1.21" +(defproject day8.re-frame/trace "0.1.22-SNAPSHOT" :description "Tracing and developer tools for re-frame apps" :url "https://github.com/Day8/re-frame-trace" :license {:name "MIT"} From efd6ba68dfdb56d328fc309755f259c9a8e4d64c Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sat, 17 Feb 2018 18:54:43 +1100 Subject: [PATCH 02/22] Update UnderstandingTiming.md --- .../UnderstandingTiming.md | 20 ++++++++----------- 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/HyperlinkedInformation/UnderstandingTiming.md b/docs/HyperlinkedInformation/UnderstandingTiming.md index e387f76..b3acadd 100644 --- a/docs/HyperlinkedInformation/UnderstandingTiming.md +++ b/docs/HyperlinkedInformation/UnderstandingTiming.md @@ -1,6 +1,6 @@ -This document highlights important aspects of the "Timing" tab. +A few notes on the "Timing" tab in `re-frame-trace`. -## Be Cautious And Sceptical +### Be Cautious And Sceptical There are two issues with the displayed numbers: @@ -8,15 +8,11 @@ There are two issues with the displayed numbers: a fool's errand. One moment it takes 1ms and the next it takes 10ms, and you’ll never know why. Noisy. - So, don't ever base your decisions on one set of timings. Run - the same event at least a few of times. + So, don't ever base your decisions on one set of timings. + Click the "rerun" button (#115) a few times to see if you + get stable numbers. - In the future, we'd like to add a 'Run It Again' button, which - you can click a few times to see if you get stable numbers. - Perhaps you'll beat us to it, and create a PR for this - feature? - -2. Don't freak out about any apparent slowness, yet. +2. Don't freak out about any apparent slowness just yet. After all, you're running a dev build, right, not the production build? And I'm guessing you're also @@ -35,7 +31,7 @@ There are two issues with the displayed numbers: reason, compared to others? And, even then, remember point 1 (above). -## Know Your Epoch Timeline +### Know Your Epoch Timeline The Timing Tab is easier to understand once you have internalised the following graphic which shows how, operationally, the six dominoes play out, @@ -43,7 +39,7 @@ over time, within the browser. -## Other Tips +### Other Tips You should probably have [React DevTools](https://github.com/facebook/react-devtools) installed because it is useful. But, it can also add drag and noise to timing results, From e993914f98ed5fac34e180d7697cc3ddbdd5a6f5 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sat, 17 Feb 2018 18:59:29 +1100 Subject: [PATCH 03/22] Update UnderstandingTiming.md --- docs/HyperlinkedInformation/UnderstandingTiming.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/HyperlinkedInformation/UnderstandingTiming.md b/docs/HyperlinkedInformation/UnderstandingTiming.md index b3acadd..aeddff9 100644 --- a/docs/HyperlinkedInformation/UnderstandingTiming.md +++ b/docs/HyperlinkedInformation/UnderstandingTiming.md @@ -1,15 +1,15 @@ -A few notes on the "Timing" tab in `re-frame-trace`. +Some notes on the "Timing" tab in `re-frame-trace`. -### Be Cautious And Sceptical +## Be Sceptical Of The Numbers -There are two issues with the displayed numbers: +Two reasons: 1. Accurately timing something in the browser is almost a fool's errand. One moment it takes 1ms and the next it takes 10ms, and you’ll never know why. Noisy. - So, don't ever base your decisions on one set of timings. - Click the "rerun" button (#115) a few times to see if you + So, don't ever base decisions on one set of timings. + Click the "rerun" button ([#115](https://github.com/Day8/re-frame-trace/issues/155)) a few times to see if you get stable numbers. 2. Don't freak out about any apparent slowness just yet. @@ -31,7 +31,7 @@ There are two issues with the displayed numbers: reason, compared to others? And, even then, remember point 1 (above). -### Know Your Epoch Timeline +## Know Your Epoch Timeline The Timing Tab is easier to understand once you have internalised the following graphic which shows how, operationally, the six dominoes play out, @@ -39,7 +39,7 @@ over time, within the browser. -### Other Tips +## Other Tips You should probably have [React DevTools](https://github.com/facebook/react-devtools) installed because it is useful. But, it can also add drag and noise to timing results, From a0d2b1405992501ab35694fa86ed5d5ea9454340 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sat, 17 Feb 2018 20:22:35 +1100 Subject: [PATCH 04/22] Update UnderstandingTiming.md --- docs/HyperlinkedInformation/UnderstandingTiming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/HyperlinkedInformation/UnderstandingTiming.md b/docs/HyperlinkedInformation/UnderstandingTiming.md index aeddff9..703070d 100644 --- a/docs/HyperlinkedInformation/UnderstandingTiming.md +++ b/docs/HyperlinkedInformation/UnderstandingTiming.md @@ -9,7 +9,7 @@ Two reasons: takes 10ms, and you’ll never know why. Noisy. So, don't ever base decisions on one set of timings. - Click the "rerun" button ([#115](https://github.com/Day8/re-frame-trace/issues/155)) a few times to see if you + Click the "replay" button ([#115](https://github.com/Day8/re-frame-trace/issues/155)) a few times to see if you get stable numbers. 2. Don't freak out about any apparent slowness just yet. From 108f2371113eff56e7d579cd9255a20dd5bd345a Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sat, 17 Feb 2018 20:28:44 +1100 Subject: [PATCH 05/22] Update UnderstandingTiming.md --- .../UnderstandingTiming.md | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/HyperlinkedInformation/UnderstandingTiming.md b/docs/HyperlinkedInformation/UnderstandingTiming.md index 703070d..d01deb3 100644 --- a/docs/HyperlinkedInformation/UnderstandingTiming.md +++ b/docs/HyperlinkedInformation/UnderstandingTiming.md @@ -12,23 +12,22 @@ Two reasons: Click the "replay" button ([#115](https://github.com/Day8/re-frame-trace/issues/155)) a few times to see if you get stable numbers. -2. Don't freak out about any apparent slowness just yet. +2. Don't freak out about any apparent slowness. Not just yet, anyway. After all, you're running a dev build, right, not the production build? And I'm guessing you're also - running a dev build of React? - - And using `re-frame-trace` will slow things - down too, what with all that creating and analysing of trace. + running a dev build of React? And even `re-frame-trace` itself will add + its own drag too, what with all that creating and analysing of trace. So, run the production version of your app first, before deciding you have a performance problem. Something what - takes 100ms in dev might take 20ms in prod. + takes 100ms in dev might take 10ms in prod. The Timing Tab is not really about absolute numbers so much as the relative time taken to do the different - "parts" of an Epoch. Is one View very slow for some - reason, compared to others? + "parts" of an Epoch. Is most the time going in views, or + maybe one view in particular? Or in + one subscription, compared to the others? And, even then, remember point 1 (above). ## Know Your Epoch Timeline @@ -41,10 +40,11 @@ over time, within the browser. ## Other Tips -You should probably have [React DevTools](https://github.com/facebook/react-devtools) -installed because it is useful. But, it can also add drag and noise to timing results, -so disable it when trying to get more accurate timing figures. +It might be useful to have [React DevTools](https://github.com/facebook/react-devtools) +installed because it can show you visually, what is rerednering. Neat idea. But, realise it +can also add drag and noise to timing results, so disable it when trying to get more +accurate timing figures. Here is (React 16) advice on [debugging React performance with Chrome Devtools](https://building.calibreapp.com/debugging-react-performance-with-react-16-and-chrome-devtools-c90698a522ad) -The [re-frame.core/debug](https://github.com/Day8/re-frame/blob/master/src/re_frame/std_interceptors.cljc) middleware is relatively slow, and runs interleaved with your application's events being processed. re-frame-trace gives you the same information in the app-db panel, but saves the calculations until after your application has finished running, so you don't get the performance cost included in your timing. +The [re-frame.core/debug](https://github.com/Day8/re-frame/blob/master/src/re_frame/std_interceptors.cljc) interceptor is relatively slow, and runs interleaved with your application's events being processed. re-frame-trace gives you the same information in the app-db panel, but saves the calculations until after your application has finished running, so you don't get the performance cost included in your timing. From 7f750aac47201c59d4bbff48f86a4e7b2a7cb7e8 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sat, 17 Feb 2018 20:34:36 +1100 Subject: [PATCH 06/22] Update UnderstandingTiming.md --- .../UnderstandingTiming.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/HyperlinkedInformation/UnderstandingTiming.md b/docs/HyperlinkedInformation/UnderstandingTiming.md index d01deb3..1cc2971 100644 --- a/docs/HyperlinkedInformation/UnderstandingTiming.md +++ b/docs/HyperlinkedInformation/UnderstandingTiming.md @@ -4,20 +4,20 @@ Some notes on the "Timing" tab in `re-frame-trace`. Two reasons: -1. Accurately timing something in the browser is almost +1. Accurately timing something in the browser is a fool's errand. One moment it takes 1ms and the next it takes 10ms, and you’ll never know why. Noisy. - So, don't ever base decisions on one set of timings. - Click the "replay" button ([#115](https://github.com/Day8/re-frame-trace/issues/155)) a few times to see if you - get stable numbers. + So, don't ever draw conclusions from one set of timings. + Click the "replay" button ([#115](https://github.com/Day8/re-frame-trace/issues/155)) + a few times to ensure the numbers are stable. -2. Don't freak out about any apparent slowness. Not just yet, anyway. +2. Don't freak out about any apparent slowness. Not initially, anyway. After all, you're running a dev build, right, not the production build? And I'm guessing you're also - running a dev build of React? And even `re-frame-trace` itself will add - its own drag too, what with all that creating and analysing of trace. + running a dev build of React? And `re-frame-trace` will itself also add + drag, what with all that creating and analysing of trace. So, run the production version of your app first, before deciding you have a performance problem. Something what @@ -28,13 +28,13 @@ Two reasons: "parts" of an Epoch. Is most the time going in views, or maybe one view in particular? Or in one subscription, compared to the others? - And, even then, remember point 1 (above). + And, even then, keep in mind point 1 (above). ## Know Your Epoch Timeline The Timing Tab is easier to understand once you have internalised the following graphic which shows how, operationally, the six dominoes play out, -over time, within the browser. +over time, within the browser. From ee264ec7f7f324d68aa9cd14c12aa99bdc61f5bf Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sat, 17 Feb 2018 22:24:28 +1100 Subject: [PATCH 07/22] Update UnchangedLayer2.md --- .../HyperlinkedInformation/UnchangedLayer2.md | 28 ++++++++++--------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/HyperlinkedInformation/UnchangedLayer2.md b/docs/HyperlinkedInformation/UnchangedLayer2.md index 97485e1..c576937 100644 --- a/docs/HyperlinkedInformation/UnchangedLayer2.md +++ b/docs/HyperlinkedInformation/UnchangedLayer2.md @@ -1,22 +1,24 @@ -This document briefly explains why `re-frame-trace` gives you an option to -ignore unchanged layer 2 subscriptions. +In the "subs" tab, you have the option to +ignore unchanged layer 2 subscriptions. This document explains why. ### Background -The `re-frame` docs -[make a distinction](https://github.com/Day8/re-frame/blob/master/docs/SubscriptionInfographic.md) +`re-frame` +[makes a distinction](https://github.com/Day8/re-frame/blob/master/docs/SubscriptionInfographic.md) between `layer 2` and `layer 3` subscriptions: - - `layer 2` subscriptions extract data directly from `app-db` and should be - trivial in nature. There should be no computation in them beyond + - **`layer 2` subscriptions extract data directly from `app-db`**. They should be + trivial in nature, which is to say there should be no computation in them beyond what is necessary to extract a value from `app-db` - - `layer 3` subscriptions take values from `layer 2` nodes as inputs, and - compute a materialised view of those values. Just to repeat: they never directly - extract values from `app-db`. They create new values where necessary, and because of it - they to do more serious CPU work. So we never want to run a - `layer 3` subscriptions unless it is necessary. + - **`layer 3` subscriptions never take values from `app-db`**. Instead, they have + `layer 2` nodes as inputs, and they do the more serious CPU work of computing + a materialised view of those values. + + +We never want to run a `layer 3` subscriptions unless it is necessary, whereas `layer 2` +subscriptions are so trivial that we don't mind running them unnecessarily. This structure delivers efficiency. You see, **all** (currently instantiated) `layer 2` subscriptions -will run **every** time `app-db` changes in any way. All of them. Every time. +**will run every time `app-db` changes in any way**. All of them. Every time. And `app-db` changes on almost every event, so we want them to be computationally trivial. @@ -25,7 +27,7 @@ propagation of values through the signal graph will be pruned. The more computationally intensive `layer 3` subscriptions, and ultimately the views, will only recompute if and when there has been a change in their data inputs. -We don't want your app recomputing views only to find that nothing has changed. Inefficient. +We don't want your app recomputing views only to find that nothing has changed. That would be inefficient. ### Back To Tracing From e14453f121604506b2c92c75bc734b5efeb35f79 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sat, 17 Feb 2018 22:27:13 +1100 Subject: [PATCH 08/22] Update UnchangedLayer2.md --- docs/HyperlinkedInformation/UnchangedLayer2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/HyperlinkedInformation/UnchangedLayer2.md b/docs/HyperlinkedInformation/UnchangedLayer2.md index c576937..cecccb8 100644 --- a/docs/HyperlinkedInformation/UnchangedLayer2.md +++ b/docs/HyperlinkedInformation/UnchangedLayer2.md @@ -10,7 +10,7 @@ between `layer 2` and `layer 3` subscriptions: trivial in nature, which is to say there should be no computation in them beyond what is necessary to extract a value from `app-db` - **`layer 3` subscriptions never take values from `app-db`**. Instead, they have - `layer 2` nodes as inputs, and they do the more serious CPU work of computing + `layer 2` nodes as inputs (or other `layer 3`), and they do the more serious CPU work of computing a materialised view of those values. From ad084d45da322cc5f0a8f95eed420f82f67d8ae2 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 00:13:29 +1100 Subject: [PATCH 09/22] Create ReplayButton.md --- docs/HyperlinkedInformation/ReplayButton.md | 32 +++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 docs/HyperlinkedInformation/ReplayButton.md diff --git a/docs/HyperlinkedInformation/ReplayButton.md b/docs/HyperlinkedInformation/ReplayButton.md new file mode 100644 index 0000000..c6a7a7a --- /dev/null +++ b/docs/HyperlinkedInformation/ReplayButton.md @@ -0,0 +1,32 @@ +This document explains the operation of the "Replay" button, and how to use a **HotPlay Loop**. + +By using the backwards and forwards arrows, `re-frame-trace` allows you to navigate through Epochs. +At any one time, you can be inspecting a single Epoch, which we'll term "The Observed Epoch". + +When you click the "Replay" button, you are asking `re-frame-trace` to perform +an "Action Replay" of "The Observed Epoch", and this happens in two Steps: +1. the value in `app-db` is reset to the value it had immediately prior to "The Observed Epoch" +2. the event which caused "The Observed Epoch" is re-dispatched + +Further Notes: + - In Step 1, the reset of `app-db` will trigger + subscriptions and views to rerun, as the application returns to the "prior state" + but none of this trace is captured. It is all ignored. + - All trace arising in Step 2 forms a normal, new Epoch. The (original) Observed Epoch is + still there untouched. + - The new Epoch (Step 2) is added to the end of the existing Epoch list. It is the newest, most recent Epoch. + - The user is auto-navigated to view this new epoch. So the user + immediately sees the results for this new Epoch - the timings etc. + +## Useful? + +Hell, yes, massively. There's a productive development process we call "A HotPlay Loop" which works like this: + - A. You **observe** an Epoch (in `re-frame-trace`) to see if an event was correctly processed + - B. You notice a problem, and you **edit** (correct) the event handler (or subscription handler, view, etc). + - C. Figwheel will re-compile and **Hotload** your correction + - D: You click the **Replay** button + - E: Back to A + +The initials of this process are OEHR, which doesn't exactly roll off the tounge like REPL. +So we just call it "The HotPlay Loop" (Hotload and Replay). + From ddb0875171e0ac039892df88b723809cee39a182 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 00:16:37 +1100 Subject: [PATCH 10/22] Update ReplayButton.md --- docs/HyperlinkedInformation/ReplayButton.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/HyperlinkedInformation/ReplayButton.md b/docs/HyperlinkedInformation/ReplayButton.md index c6a7a7a..9c4c1cb 100644 --- a/docs/HyperlinkedInformation/ReplayButton.md +++ b/docs/HyperlinkedInformation/ReplayButton.md @@ -9,11 +9,11 @@ an "Action Replay" of "The Observed Epoch", and this happens in two Steps: 2. the event which caused "The Observed Epoch" is re-dispatched Further Notes: - - In Step 1, the reset of `app-db` will trigger + - In Step 1, the reset of `app-db` will trigger dominoes 4,5,6, causing subscriptions and views to rerun, as the application returns to the "prior state" but none of this trace is captured. It is all ignored. - All trace arising in Step 2 forms a normal, new Epoch. The (original) Observed Epoch is - still there untouched. + still there, untouched. - The new Epoch (Step 2) is added to the end of the existing Epoch list. It is the newest, most recent Epoch. - The user is auto-navigated to view this new epoch. So the user immediately sees the results for this new Epoch - the timings etc. From 4332517e2584fd534fb195da99128007c5dfbcf5 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 00:17:16 +1100 Subject: [PATCH 11/22] Update ReplayButton.md --- docs/HyperlinkedInformation/ReplayButton.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/HyperlinkedInformation/ReplayButton.md b/docs/HyperlinkedInformation/ReplayButton.md index 9c4c1cb..6ea4c30 100644 --- a/docs/HyperlinkedInformation/ReplayButton.md +++ b/docs/HyperlinkedInformation/ReplayButton.md @@ -18,7 +18,7 @@ Further Notes: - The user is auto-navigated to view this new epoch. So the user immediately sees the results for this new Epoch - the timings etc. -## Useful? +### Useful? Hell, yes, massively. There's a productive development process we call "A HotPlay Loop" which works like this: - A. You **observe** an Epoch (in `re-frame-trace`) to see if an event was correctly processed From 611e470fbaaa868af07dede75a9f49216a955435 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 00:22:53 +1100 Subject: [PATCH 12/22] Update ReplayButton.md --- docs/HyperlinkedInformation/ReplayButton.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/HyperlinkedInformation/ReplayButton.md b/docs/HyperlinkedInformation/ReplayButton.md index 6ea4c30..eb1a79f 100644 --- a/docs/HyperlinkedInformation/ReplayButton.md +++ b/docs/HyperlinkedInformation/ReplayButton.md @@ -1,14 +1,19 @@ This document explains the operation of the "Replay" button, and how to use a **HotPlay Loop**. + +### Epoch Navigation + By using the backwards and forwards arrows, `re-frame-trace` allows you to navigate through Epochs. At any one time, you can be inspecting a single Epoch, which we'll term "The Observed Epoch". +### Click + When you click the "Replay" button, you are asking `re-frame-trace` to perform an "Action Replay" of "The Observed Epoch", and this happens in two Steps: 1. the value in `app-db` is reset to the value it had immediately prior to "The Observed Epoch" 2. the event which caused "The Observed Epoch" is re-dispatched -Further Notes: +### Further Notes: - In Step 1, the reset of `app-db` will trigger dominoes 4,5,6, causing subscriptions and views to rerun, as the application returns to the "prior state" but none of this trace is captured. It is all ignored. @@ -27,6 +32,9 @@ Hell, yes, massively. There's a productive development process we call "A HotPla - D: You click the **Replay** button - E: Back to A + +### Process Name + The initials of this process are OEHR, which doesn't exactly roll off the tounge like REPL. So we just call it "The HotPlay Loop" (Hotload and Replay). From 7163b32dbb03014e7c18584c200ac4230bf42ee6 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 08:29:56 +1100 Subject: [PATCH 13/22] Update ReplayButton.md --- docs/HyperlinkedInformation/ReplayButton.md | 50 ++++++++++++--------- 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/docs/HyperlinkedInformation/ReplayButton.md b/docs/HyperlinkedInformation/ReplayButton.md index eb1a79f..045236b 100644 --- a/docs/HyperlinkedInformation/ReplayButton.md +++ b/docs/HyperlinkedInformation/ReplayButton.md @@ -1,40 +1,48 @@ -This document explains the operation of the "Replay" button, and how to use a **HotPlay Loop**. - +This document explains the operation of the "Replay" button, and how to use **The HotPlay Workflow**. ### Epoch Navigation By using the backwards and forwards arrows, `re-frame-trace` allows you to navigate through Epochs. -At any one time, you can be inspecting a single Epoch, which we'll term "The Observed Epoch". +At any one moment, you are inspecting a single Epoch, for which we'll use the term "The Observed Epoch". -### Click +### On Click When you click the "Replay" button, you are asking `re-frame-trace` to perform an "Action Replay" of "The Observed Epoch", and this happens in two Steps: -1. the value in `app-db` is reset to the value it had immediately prior to "The Observed Epoch" -2. the event which caused "The Observed Epoch" is re-dispatched + - **Step 1** - the value in `app-db` is reset to the value it contained immediately prior to "The Observed Epoch" + - **Step 2** - the event which caused "The Observed Epoch" is re-dispatched + +So, Step 1 is "reestablish initial conditions" and Step 2 is "do it all again". ### Further Notes: - In Step 1, the reset of `app-db` will trigger dominoes 4,5,6, causing - subscriptions and views to rerun, as the application returns to the "prior state" - but none of this trace is captured. It is all ignored. - - All trace arising in Step 2 forms a normal, new Epoch. The (original) Observed Epoch is - still there, untouched. - - The new Epoch (Step 2) is added to the end of the existing Epoch list. It is the newest, most recent Epoch. - - The user is auto-navigated to view this new epoch. So the user - immediately sees the results for this new Epoch - the timings etc. + subscriptions and views to run as the application returns to the "prior state", + but none of the trace for this is captured. It is all ignored. + - All trace arising in Step 2 forms a normal, new Epoch. The (original) Observed Epoch (which we are replaying) + is still there, untouched. + - The new Epoch (Step 2) is added to the end of the existing Epoch list. It becomes the most recent Epoch. + - The user's experience is that they click the "Replay" button + and immediately view the result. So, after Step 2, the user is auto-navigated to this new epoch. ### Useful? -Hell, yes, massively. There's a productive development process we call "A HotPlay Loop" which works like this: - - A. You **observe** an Epoch (in `re-frame-trace`) to see if an event was correctly processed - - B. You notice a problem, and you **edit** (correct) the event handler (or subscription handler, view, etc). - - C. Figwheel will re-compile and **Hotload** your correction - - D: You click the **Replay** button +It facilitates "The HotPlay Workflow": + - A. You `Observe` an Epoch (in `re-frame-trace`) to see if an event was correctly processed + - B. You notice a problem, and you `Edit` (correct) the event handler (or subs handler, view, etc) via Cursive, Emacs, etc. + - C. Figwheel will re-compile and `Hotload` your correction + - D: You click the `Replay` button - E: Back to A +Because of `Replay's` "Step 1", you effortlessly get identical "initial conditions" +each iteration of the workflow, which removes a lot of incidental cognative load +(struggling around trying to put the application back into the right state for each new iteration) +and keeps the iterations snappy. Flow. -### Process Name +WARNING: obviously this works best when the state is contained in your SPA. When +there's remote state (a remote database?) it gets trickier to return to initial conditions. -The initials of this process are OEHR, which doesn't exactly roll off the tounge like REPL. -So we just call it "The HotPlay Loop" (Hotload and Replay). +### The Workflow Name + +The initials of this Observe/Edit/Hotload/Replay process are OEHR, which, will, it doesn't exactly roll off the tounge like REPL. +So we call it "HotPlay" because "Hotload" and "Replay" are the two central pieces of tech. We love you Figwheel. From 6effae5c701939897e9f507fafb87582d68bd020 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 08:44:02 +1100 Subject: [PATCH 14/22] Update ReplayButton.md --- docs/HyperlinkedInformation/ReplayButton.md | 25 +++++++++++---------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/HyperlinkedInformation/ReplayButton.md b/docs/HyperlinkedInformation/ReplayButton.md index 045236b..f4d5f9f 100644 --- a/docs/HyperlinkedInformation/ReplayButton.md +++ b/docs/HyperlinkedInformation/ReplayButton.md @@ -15,12 +15,12 @@ an "Action Replay" of "The Observed Epoch", and this happens in two Steps: So, Step 1 is "reestablish initial conditions" and Step 2 is "do it all again". ### Further Notes: - - In Step 1, the reset of `app-db` will trigger dominoes 4,5,6, causing - subscriptions and views to run as the application returns to the "prior state", - but none of the trace for this is captured. It is all ignored. - - All trace arising in Step 2 forms a normal, new Epoch. The (original) Observed Epoch (which we are replaying) + - In Step 1, the reset of `app-db` will trigger computation and trace. + Subscriptions and views are run as the application returns to the "prior state", + but none of the associated trace is captured. It is all ignored. + - Trace arising from Step 2 forms a normal, new Epoch. The Observed Epoch (which we are replaying) is still there, untouched. - - The new Epoch (Step 2) is added to the end of the existing Epoch list. It becomes the most recent Epoch. + - New Epochs (Step 2) are always added to the end of the Epoch list (never inserted amongst old Epochs). - The user's experience is that they click the "Replay" button and immediately view the result. So, after Step 2, the user is auto-navigated to this new epoch. @@ -28,18 +28,19 @@ So, Step 1 is "reestablish initial conditions" and Step 2 is "do it all again". It facilitates "The HotPlay Workflow": - A. You `Observe` an Epoch (in `re-frame-trace`) to see if an event was correctly processed - - B. You notice a problem, and you `Edit` (correct) the event handler (or subs handler, view, etc) via Cursive, Emacs, etc. + - B. You notice a problem, and you `Edit` (fix) the event handler (or subs handler, view, etc) via Cursive, Emacs, etc. - C. Figwheel will re-compile and `Hotload` your correction - D: You click the `Replay` button - E: Back to A -Because of `Replay's` "Step 1", you effortlessly get identical "initial conditions" -each iteration of the workflow, which removes a lot of incidental cognative load -(struggling around trying to put the application back into the right state for each new iteration) -and keeps the iterations snappy. Flow. +Because of `Replay's` "Step 1", you effortlessly get identical "initial conditions" for +each iteration of the workflow, and this is true blessing. It removes the nagging +cognative load of "allowing for" slightly shifting state. Or the effort of manually +reestablishing identical application state before each iteration. -WARNING: obviously this works best when the state is contained in your SPA. When -there's remote state (a remote database?) it gets trickier to return to initial conditions. +WARNING: obviously this only works when the state is contained in your SPA. When +there's remote state (a remote database?) it is more effort to return to initial conditions +each iteration. ### The Workflow Name From a8aa92be68dc49e94180dc557443a021048ce799 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 08:58:43 +1100 Subject: [PATCH 15/22] Update ReplayButton.md --- docs/HyperlinkedInformation/ReplayButton.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/HyperlinkedInformation/ReplayButton.md b/docs/HyperlinkedInformation/ReplayButton.md index f4d5f9f..f3e4334 100644 --- a/docs/HyperlinkedInformation/ReplayButton.md +++ b/docs/HyperlinkedInformation/ReplayButton.md @@ -14,7 +14,7 @@ an "Action Replay" of "The Observed Epoch", and this happens in two Steps: So, Step 1 is "reestablish initial conditions" and Step 2 is "do it all again". -### Further Notes: +#### Further Notes: - In Step 1, the reset of `app-db` will trigger computation and trace. Subscriptions and views are run as the application returns to the "prior state", but none of the associated trace is captured. It is all ignored. @@ -33,17 +33,17 @@ It facilitates "The HotPlay Workflow": - D: You click the `Replay` button - E: Back to A -Because of `Replay's` "Step 1", you effortlessly get identical "initial conditions" for +Because of `Replay's` "Step 1", you get identical "initial conditions" for each iteration of the workflow, and this is true blessing. It removes the nagging -cognative load of "allowing for" slightly shifting state. Or the effort of manually -reestablishing identical application state before each iteration. +cognative load of "allowing for" slightly shifting state and its consequences, or +the effort of manually reestablishing identical application state before each iteration. -WARNING: obviously this only works when the state is contained in your SPA. When -there's remote state (a remote database?) it is more effort to return to initial conditions -each iteration. +WARNING: obviously this only works when the state is contained within your SPA. When +there's authorative remote state (a remote database?) there'll be more involved in +returning to initial conditions each iteration. ### The Workflow Name -The initials of this Observe/Edit/Hotload/Replay process are OEHR, which, will, it doesn't exactly roll off the tounge like REPL. +The initials of this Observe/Edit/Hotload/Replay process are OEHR, which, well, doesn't exactly roll off the tounge like REPL. So we call it "HotPlay" because "Hotload" and "Replay" are the two central pieces of tech. We love you Figwheel. From e4d31177b218dbcdab549843524c5a7daf2feb14 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 12:54:54 +1100 Subject: [PATCH 16/22] Update README.md --- docs/HyperlinkedInformation/README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/HyperlinkedInformation/README.md b/docs/HyperlinkedInformation/README.md index 28b5c98..1f5f743 100644 --- a/docs/HyperlinkedInformation/README.md +++ b/docs/HyperlinkedInformation/README.md @@ -1,4 +1 @@ -This directory holds help documents accessed directly from the UI. - -The `re-frame-trace` UI contains -various (helpful) hyperlinks which point to documents kept within this directory. +The `re-frame-trace` UI contains hyperlinks to the various documents in this directory. Within the UI, these hyperlinks have text like "guide me to greatness" and "why?", which indicates the purpose of the docs herein. From 7f1f000d67f8d2b1c2e1a1b28922d7e2241e3df0 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 13:40:24 +1100 Subject: [PATCH 17/22] Update README.md --- README.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 553cd75..6e2340e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # re-frame-trace -`re-frame-trace` let's you inspect the inner workings of a running `re-frame` application. It presents as a programmer's dashboard, delivering curated insight and illumination. A 10x programmer is the one with 10x more knowledge and insight. +`re-frame-trace` let's you instrument, and then inspect, the inner workings of a running `re-frame` application. It presents as a programmer's dashboard, delivering curated insight and illumination. ### It Is Epoch Oriented @@ -99,11 +99,13 @@ features, and build a cognative map of how the code is structured. > Some of the claims above are aspirational. `re-frame-trace` [remains a WIP](https://github.com/Day8/re-frame-trace/issues/118). -## Sausage +## Of Sausage And Sizzle -We debated internally about the name `re-frame-trace`. While `-trace` is accurate, it is 100% sausage because it talks about low level function, and not higher level benefit (sizzle, sizzle). I wanted to call it `vox-datum` (voice of the data) but that was cruelly rejected, for reasons I don't care to remember. The pain. I mean, who the hell doesn't like a Latin name?? Philistines. Anyway, `-insight` and `-illumination` are the benefits, but they made the name waaaay too long. Naming things - it's just a nightmare! As is inertia. So, `-trace` it remains. +Internal discussion about a name meandered unproductively for a while. Initially, it was `re-frame-trace`, which is accurate, sure, but it is also 100% sausage because it talks about low level function, and not higher level benefit (sizzle, sizzle). Side stepping the issue, I wanted to call it `vox-datum` (voice of the data) but that was cruelly rejected, for reasons I don't care to remember. The pain. I mean, who the hell doesn't like a Latin name?? Philistines. -**Update:** a name change to `re-frame-10x` is on the cards. Disapointingly, my latest suggestion, `TenMinutesByTractor`, was also rejected. I shake my head. Why can noone see that we're all "code farmers" by profession? +Now, the benifits are `-insight` and `-illumination`, but adding either made the name waaaay too long. Naming things - it's just a nightmare! Who knew? + +Finally, `-10x` cheekily materialised, delivering over 100 decibels of audacious sizzle, and consequently an expectation for us to live up to. A 10x programmer starts by having 10x more knowledge and insight - so make that tool, smarty pants. ## A Visual Sampler From 5514620201149428c7b906598eb0acdf084a30db Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 13:41:11 +1100 Subject: [PATCH 18/22] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6e2340e..6c6933c 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,7 @@ Now, the benifits are `-insight` and `-illumination`, but adding either made the Finally, `-10x` cheekily materialised, delivering over 100 decibels of audacious sizzle, and consequently an expectation for us to live up to. A 10x programmer starts by having 10x more knowledge and insight - so make that tool, smarty pants. -## A Visual Sampler +## A 1000 words Slightly out of date, but indicative ... From af08c0224eec2392b6ff57683c8834a16c6639f4 Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 14:33:01 +1100 Subject: [PATCH 19/22] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6c6933c..5002af9 100644 --- a/README.md +++ b/README.md @@ -101,11 +101,11 @@ features, and build a cognative map of how the code is structured. ## Of Sausage And Sizzle -Internal discussion about a name meandered unproductively for a while. Initially, it was `re-frame-trace`, which is accurate, sure, but it is also 100% sausage because it talks about low level function, and not higher level benefit (sizzle, sizzle). Side stepping the issue, I wanted to call it `vox-datum` (voice of the data) but that was cruelly rejected, for reasons I don't care to remember. The pain. I mean, who the hell doesn't like a Latin name?? Philistines. +Internal discussion about a name meandered for a while. Initially, it was `re-frame-trace`, which is accurate, sure, but it is also 100% sausage because it talks about low level function, and not higher level benefit (sizzle, sizzle). Side stepping the issue, I wanted to call it `vox-datum` (voice of the data) but that was cruelly rejected, for reasons I don't care to remember. The pain. I mean, who the hell doesn't like a Latin name?? Philistines. Now, the benifits are `-insight` and `-illumination`, but adding either made the name waaaay too long. Naming things - it's just a nightmare! Who knew? -Finally, `-10x` cheekily materialised, delivering over 100 decibels of audacious sizzle, and consequently an expectation for us to live up to. A 10x programmer starts by having 10x more knowledge and insight - so make that tool, smarty pants. +Finally, `-10x` cheekily materialised, delivering 100 decibels of audacious sizzle, and consequently a challenge for us to live up to. A 10x programmer starts by having 10x more knowledge and insight - so make that tool, smarty pants. ## A 1000 words From ba88153e0973fc06d768a03eb904dc0116735ffe Mon Sep 17 00:00:00 2001 From: Mike Thompson Date: Sun, 18 Feb 2018 23:43:16 +1100 Subject: [PATCH 20/22] Update README.md --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5002af9..28bbdab 100644 --- a/README.md +++ b/README.md @@ -103,9 +103,9 @@ features, and build a cognative map of how the code is structured. Internal discussion about a name meandered for a while. Initially, it was `re-frame-trace`, which is accurate, sure, but it is also 100% sausage because it talks about low level function, and not higher level benefit (sizzle, sizzle). Side stepping the issue, I wanted to call it `vox-datum` (voice of the data) but that was cruelly rejected, for reasons I don't care to remember. The pain. I mean, who the hell doesn't like a Latin name?? Philistines. -Now, the benifits are `-insight` and `-illumination`, but adding either made the name waaaay too long. Naming things - it's just a nightmare! Who knew? +Now, the tool's benifits are `-insight` and `-illumination`, but adding either made the name waaaay too long. Naming things - it really is a nightmare! -Finally, `-10x` cheekily materialised, delivering 100 decibels of audacious sizzle, and consequently a challenge for us to live up to. A 10x programmer starts by having 10x more knowledge and insight - so make that tool, smarty pants. +Finally, `-10x` cheekily materialised, delivering 100 decibels of audacious sizzle, and consequently a challenge for us to live up to. A 10x programmer starts by having 10x more knowledge and insight - so go make that tool, smarty pants. ## A 1000 words From 92227465e81f71241c86e3b0121829cf9b323c3a Mon Sep 17 00:00:00 2001 From: Daniel Compton Date: Tue, 20 Feb 2018 14:24:35 +1300 Subject: [PATCH 21/22] Add warning for people that upgrade to newer versions If someone used something like lein-ancient to upgrade their libraries, they might not realise that re-frame-trace has been renamed to re-frame-10x. This commit will log a warning every time it is loaded, to tell people that they should use the new 10x version. --- src/day8/re_frame/trace/preload.cljs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/day8/re_frame/trace/preload.cljs b/src/day8/re_frame/trace/preload.cljs index 68d37d9..6e443cd 100644 --- a/src/day8/re_frame/trace/preload.cljs +++ b/src/day8/re_frame/trace/preload.cljs @@ -5,6 +5,7 @@ ;; Use this namespace with the :preloads compiler option to perform the necessary setup for enabling tracing: ;; {:compiler {:preloads [day8.re-frame.trace.preload] ...}} +(js/console.warn "re-frame-trace has been renamed to re-frame-10x: (https://clojars.org/day8.re-frame/re-frame-10x). Update to newer versions of this library by using the `day8.re-frame/re-frame-10x` artifact ID. Thanks!") (rf/clear-subscription-cache!) (trace/init-db!) (defonce _ (trace/init-tracing!)) From bed95ef7c841a60b603962099a5c449b43537a92 Mon Sep 17 00:00:00 2001 From: Daniel Compton Date: Tue, 20 Feb 2018 14:25:58 +1300 Subject: [PATCH 22/22] Version 0.1.22 --- project.clj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/project.clj b/project.clj index 80334b2..99cc325 100644 --- a/project.clj +++ b/project.clj @@ -1,4 +1,4 @@ -(defproject day8.re-frame/trace "0.1.22-SNAPSHOT" +(defproject day8.re-frame/trace "0.1.22" :description "Tracing and developer tools for re-frame apps" :url "https://github.com/Day8/re-frame-trace" :license {:name "MIT"}