kennel 1.113.3 → 1.114.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1820e573733a40ccb56114ecc6c94f8d7732feb10d556f3bf1107c9d21fab7f0
-  data.tar.gz: ed5230938e75e643c71b719f6ec4e3e317e9e94d9fb1a2848bbbe881eea56f4e
+  metadata.gz: b1266c924cd004d26036f81424b92ca52cf0720f041a6cc1ee0a7d1533b19f93
+  data.tar.gz: 250117caacd886189bde046f5a8166746a8cd6b87c7330fc106954cf4c7fae20
 SHA512:
-  metadata.gz: beb8e6d2a60fd3c8ebe26cdd14ca70d89b9a107ee0a831cea52601464b7c13afe058f25eaee76add474e728f404d4c56216eea24e5ce4c5a5b58897da1e43af0
-  data.tar.gz: 8000438dd34c1e22334283f2e3892379cc08fadeb6085d74ecd41a3b32fdc0aacb28b9a2019d6bdad7a48bcea94084200f69d8c814054fe928aedf16b06b7ea2
+  metadata.gz: aba95188ef4c6c2b7e974f53ba60ad3aac21b29dcb353bc6b05790374ba0a0c4113c0dd316e1e84975723a8d4d4e117102c13d18e18ddf7050fa97931b506af8
+  data.tar.gz: 15903c3da36d10fd42220431da69ac76c7c95d1407771e2f7c5c6bb0dfe132c2054e32131ba12b149eb41c52ebfb17f3004bdc78aab6a54c7f28600515a08632

data/Readme.md

@@ -72,6 +72,95 @@ end
  - `parts/` monitors/dashboards/etc that are used by multiple projects
  - `generated/` projects as json, to show current state and proposed changes in PRs
 
+## About the models
+
+Kennel provides several classes which act as models for different purposes:
+
+* `Kennel::Models::Dashboard`, `Kennel::Models::Monitor`, `Kennel::Models::Slo`, `Kennel::Models::SyntheticTest`;
+  these models represent the various Datadog objects
+* `Kennel::Models::Project`; a container for a collection of Datadog objects
+* `Kennel::Models::Team`; provides defaults and values (e.g. tags, mentions) for the other models.
+
+After loading all the `*.rb` files under `projects/`, Kennel's starting point
+is to find all the subclasses of `Kennel::Models::Project`, and for each one,
+create an instance of that subclass (via `.new`) and then call `#parts` on that
+instance. `parts` should return a collection of the Datadog-objects (Dashboard / Monitor / etc).
+
+### Model Settings
+
+Each of the models defines various settings; for example, a Monitor has `name`, `message`,
+`type`, `query`, `tags`, and many more.
+
+When defining a subclass of a model, one can use `defaults` to provide default values for
+those settings:
+
+```Ruby
+class MyMonitor < Kennel::Models::Monitor
+  defaults(
+    name: "Error rate",
+    type: "query alert",
+    critical: 5.0,
+    query: -> {
+      "some datadog metric expression > #{critical}"
+    },
+    # ...
+  )
+end
+```
+
+This is equivalent to defining instance methods of those names, which return those values:
+
+```Ruby
+class MyMonitor < Kennel::Models::Monitor
+  def name
+    "Error rate"
+  end
+
+  def type
+    "query alert"
+  end
+
+  def critical
+    5.0
+  end
+
+  def query
+    "some datadog metric expression > #{critical}"
+  end
+end
+```
+
+except that `defaults` will complain if you try to use a setting name which doesn't
+exist. Note also that you can use either plain values (`critical: 5.0`), or procs
+(`query: -> { ... }`). Using a plain value is equivalent to using a proc which returns
+that same value; use whichever suits you best.
+
+When you _instantiate_ a model class, you can pass settings in the constructor, after
+the project:
+
+```Ruby
+project = Kennel::Models::Project.new
+my_monitor = MyMonitor.new(
+  project,
+  critical: 10.0,
+  message: -> {
+    <<~MESSAGE
+      Something bad is happening and you should be worried.
+
+      #{super()}
+    MESSAGE
+  },
+)
+```
+
+This works just like `defaults` (it checks the setting names, and it accepts
+either plain values or procs), but it applies just to this instance of the class,
+rather than to the class as a whole (i.e. it defines singleton methods, rather
+than instance methods).
+
+Most of the examples in this Readme use the proc syntax (`critical: -> { 5.0 }`) but
+for simple constants you may prefer to use the plain syntax (`critical: 5.0`).
+
 ## Workflows
 <!-- ONLY IN template/Readme.md
 

data/lib/kennel/settings_as_methods.rb

@@ -3,6 +3,16 @@ module Kennel
   module SettingsAsMethods
     SETTING_OVERRIDABLE_METHODS = [].freeze
 
+    AS_PROCS = ->(options) do
+      options.transform_values do |v|
+        if v.class == Proc
+          v
+        else
+          -> { v }
+        end
+      end
+    end
+
     def self.included(base)
       base.extend ClassMethods
       base.instance_variable_set(:@settings, [])
@@ -31,7 +41,7 @@ module Kennel
       end
 
       def defaults(options)
-        options.each do |name, block|
+        AS_PROCS.call(options).each do |name, block|
           validate_setting_exist name
           define_method name, &block
         end
@@ -58,12 +68,7 @@ module Kennel
         raise ArgumentError, "Expected #{self.class.name}.new options to be a Hash, got a #{options.class}"
       end
 
-      options.each do |k, v|
-        next if v.class == Proc
-        raise ArgumentError, "Expected #{self.class.name}.new option :#{k} to be Proc, for example `#{k}: -> { 12 }`"
-      end
-
-      options.each do |name, block|
+      AS_PROCS.call(options).each do |name, block|
         self.class.send :validate_setting_exist, name
         define_singleton_method name, &block
       end

data/lib/kennel/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Kennel
-  VERSION = "1.113.3"
+  VERSION = "1.114.0"
 end

data/template/Readme.md

@@ -56,6 +56,95 @@ end
  - `parts/` monitors/dashboards/etc that are used by multiple projects
  - `generated/` projects as json, to show current state and proposed changes in PRs
 
+## About the models
+
+Kennel provides several classes which act as models for different purposes:
+
+* `Kennel::Models::Dashboard`, `Kennel::Models::Monitor`, `Kennel::Models::Slo`, `Kennel::Models::SyntheticTest`;
+  these models represent the various Datadog objects
+* `Kennel::Models::Project`; a container for a collection of Datadog objects
+* `Kennel::Models::Team`; provides defaults and values (e.g. tags, mentions) for the other models.
+
+After loading all the `*.rb` files under `projects/`, Kennel's starting point
+is to find all the subclasses of `Kennel::Models::Project`, and for each one,
+create an instance of that subclass (via `.new`) and then call `#parts` on that
+instance. `parts` should return a collection of the Datadog-objects (Dashboard / Monitor / etc).
+
+### Model Settings
+
+Each of the models defines various settings; for example, a Monitor has `name`, `message`,
+`type`, `query`, `tags`, and many more.
+
+When defining a subclass of a model, one can use `defaults` to provide default values for
+those settings:
+
+```Ruby
+class MyMonitor < Kennel::Models::Monitor
+  defaults(
+    name: "Error rate",
+    type: "query alert",
+    critical: 5.0,
+    query: -> {
+      "some datadog metric expression > #{critical}"
+    },
+    # ...
+  )
+end
+```
+
+This is equivalent to defining instance methods of those names, which return those values:
+
+```Ruby
+class MyMonitor < Kennel::Models::Monitor
+  def name
+    "Error rate"
+  end
+
+  def type
+    "query alert"
+  end
+
+  def critical
+    5.0
+  end
+
+  def query
+    "some datadog metric expression > #{critical}"
+  end
+end
+```
+
+except that `defaults` will complain if you try to use a setting name which doesn't
+exist. Note also that you can use either plain values (`critical: 5.0`), or procs
+(`query: -> { ... }`). Using a plain value is equivalent to using a proc which returns
+that same value; use whichever suits you best.
+
+When you _instantiate_ a model class, you can pass settings in the constructor, after
+the project:
+
+```Ruby
+project = Kennel::Models::Project.new
+my_monitor = MyMonitor.new(
+  project,
+  critical: 10.0,
+  message: -> {
+    <<~MESSAGE
+      Something bad is happening and you should be worried.
+
+      #{super()}
+    MESSAGE
+  },
+)
+```
+
+This works just like `defaults` (it checks the setting names, and it accepts
+either plain values or procs), but it applies just to this instance of the class,
+rather than to the class as a whole (i.e. it defines singleton methods, rather
+than instance methods).
+
+Most of the examples in this Readme use the proc syntax (`critical: -> { 5.0 }`) but
+for simple constants you may prefer to use the plain syntax (`critical: 5.0`).
+
 ## Workflows
 
 ### Setup

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kennel
 version: !ruby/object:Gem::Version
-  version: 1.113.3
+  version: 1.114.0
 platform: ruby
 authors:
 - Michael Grosser
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-06-27 00:00:00.000000000 Z
+date: 2022-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday