[nop] Misc housekeeping

CHANGELOG.md

@@ -4,11 +4,12 @@ This project uses [**Break Versioning**](https://www.taoensso.com/break-versioni
 
 # `v1.0.0-beta1` (2024-04-19)
 
-> 📦 [Available on Clojars](https://clojars.org/com.taoensso/telemere/versions/1.0.0-beta1), this project uses [Break Versioning](https://www.taoensso.com/break-versioning).
+> **Dep/s**: [Telemere](https://clojars.org/com.taoensso/telemere/versions/1.0.0-beta1) and [Telemere SLF4J provider](https://clojars.org/com.taoensso/slf4j-telemere) are on Clojars.  
+> **Versioning**: Telemere uses [Break Versioning](https://www.taoensso.com/break-versioning).
 
 This is Telemere's first public pre-release and mostly intended for early testers and those that'd like to give feedback.
 
-While no significant changes are expected before the [planned v1.0 final release](https://www.taoensso.com/roadmap), you probably don't want to use this in production just yet.
+While no significant changes are expected before the [planned v1.0 final release](https://www.taoensso.com/roadmap), you **probably don't want to use this in production** just yet.
 
 **Please report any unexpected problems** and let me know if anything is unclear, inconvenient, etc. Now's the ideal time to get any last-minute changes in. Thank you! 🙏
 

README.md

@@ -13,7 +13,7 @@ It helps enable Clojure/Script systems that are **observable**, **robust**, and
 
 ## Latest release/s
 
-- `v1.0.0-beta1`: [release info](https://clojars.org/com.taoensso/telemere/versions/1.0.0-beta1)
+- `v1.0.0-beta1`: [release info](../../releases/tag/v1.0.0-beta1)
 
 [![Main tests][Main tests SVG]][Main tests URL]
 [![Graal tests][Graal tests SVG]][Graal tests URL]
@@ -35,7 +35,7 @@ See [here][GitHub releases] for earlier releases.
 
 #### Scaling
 
-- Hyper-optimized and **blazing fast**, see [benchmarks](#performance).
+- Hyper-optimized and **blazing fast**, see [benchmarks](#benchmarks).
 - An API that **scales comfortably** from the smallest disposable code, to the most massive and complex real-world production environments.
 
 #### Flexibility

resources/signal-docstrings/signal-options.txt

@@ -16,10 +16,10 @@ Signal options (shared by all signal creators):
 
 `:ctx` --------- Custom ?val to override auto (dynamic `*ctx*`) in signal
 `:parent` ------ Custom ?{:keys [id uid]} to override auto (dynamic) parent signal info in signal
-`:location` ---- Custom ?{:keys [ns line column file]} to override auto signal call location
+`:location` ---- Custom ?{:keys [ns line column file]} to override auto signal creator callsite location
 
 `:elidable?` --- Should signal be subject to compile-time elision? (Default: true).
-`:sample-rate` - ?rate ∈ℝ[0,1] for call sampling (0.75 => allow 75% of signals, nil => allow all)
+`:sample-rate` - ?rate ∈ℝ[0,1] for signal sampling (0.75 => allow 75% of signals, nil => allow all)
 `:when` -------- Arb ?form; when present, form must return truthy to allow signal
 `:rate-limit` -- ?spec as given to `taoensso.telemere/rate-limiter`, see its docstring for details
 `:middleware` -- ?[(fn [signal])=>modified-signal ...] signal middleware

resources/signal-docstrings/spy!.txt

@@ -25,7 +25,7 @@ Tips:
   - Test using `with-signal`: (with-signal (spy! ...)).
   - Supports the same options [2] as other signals [1].
 
-  - Identical to `trace!`, but emphasizing form + level rather than form + id.
+  - Identical to `trace!`, but emphasizes form + level rather than form + id.
 
   - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
   - Execution of `form` arg may create additional (nested) signals.

resources/signal-docstrings/trace!.txt

@@ -25,7 +25,7 @@ Tips:
   - Test using `with-signal`: (with-signal (trace! ...)).
   - Supports the same options [2] as other signals [1].
 
-  - Identical to `spy!`, but emphasizing form + id rather than form + level.
+  - Identical to `spy!`, but emphasizes form + id rather than form + level.
 
   - Useful for debugging/monitoring forms, and tracing (nested) execution flow.
   - Execution of `form` arg may create additional (nested) signals.

src/taoensso/telemere.cljc

@@ -36,11 +36,8 @@
 (enc/assert-min-encore-version [3 103 0])
 
 ;;;; TODO
-;; - Review, TODOs, missing docstrings
-;; - Reading plan, wiki docs, explainer/demo video
 ;; - Add email handler
-;;
-;; - Next OpenTelemetry tools (traces, etc.)
+;; - Native OpenTelemetry traces and spans
 ;; - Update Tufte  (signal API, config API, signal keys, etc.)
 ;; - Update Timbre (signal API, config API, signal keys, backport improvements)
 

wiki/7-Tips.md

@@ -86,7 +86,11 @@ Consider the [differences](https://www.youtube.com/watch?v=oyLBGkS5ICk) between
   
 - **Signal sampling** and **handler sampling**  are **multiplicative**.
   
-  If a signal is created with *20%* sampling and a handler handles *50%* of given signals, then *10%* of possible signals will be handled. This multiplicative rate is helpfully reflected in each signal's final `:sample-rate` value.
+  If a signal is created with *20%* sampling and a handler handles *50%* of given signals, then *10%* of possible signals will be handled.
+  
+  This multiplicative rate is helpfully reflected in each signal's final `:sample-rate` value, making it possible to estimate unsampled cardinalities in relevant cases.
+  
+  So for `n` randomly sampled signals matching some criteria, you'd have seen an estimated `Σ(1.0/sample-rate_i)` such signals _without_ sampling, etc.
   
 - Middleware can return any type, but it's best to return only `nil` or a map.
 - Middleware can be used to **filter signals** by returning `nil`.