Merge pull request #183 from lyrasis/release-4-0-0

Release 4 0 0

CHANGELOG.adoc

@@ -22,18 +22,33 @@ toc::[]
 
 == Planned for a future release
 === Breaking
-* Removal of nested `job.show_me`, `job.tell_me`, and `job.verbosity` config settings (deprecated in 3.2.0)
 * Removal of `sep` parameter in `Deduplicate::GroupedFieldValues` (deprecated in 3.3.0)
 * Removal of `multival` parameter in `Cspace::NormalizeForId`  (deprecated in 3.3.0)
 
 == Unreleased
 These changes are merged into the `main` branch, but have not been released. After merging pull requests (PRs) that are not immediately released into `main`, a tag is added appending the PR# to the current release. For example, if the release version/tag is `3.2.1`, and PR# 107 is merged without a new release, the state of the codebase after that merge will be tagged as `3.2.1.107`.
 
 === Breaking
+
+=== Added
+
+=== Changed
+
+=== Deleted
+
+=== Deprecated/Will break in a future version
+
+=== Dev
+
+== Releases
+
+=== 4.0.0 - 2023-09-11
+==== Breaking
+* Nested `job.show_me`, `job.tell_me`, and `job.verbosity` config settings have been removed. (They were deprecated in 3.2.0)
 * `Kiba::Common::Sources` and `Kiba::Common::Destinations` are no longer supported. To use an external source or destination class, subclass it in a `Kiba::Extend` source or destination class that extends `Kiba::Extend::Sourceable` or `Kiba::Extend::Destinationable` (PR#139)
 * Using a supplied file registry entry as the destination of a job raises an error, since the definition of a supplied entry is that it is not created by a job in the project. (PR#139)
 
-=== Added
+==== Added
 .New destinations
 * `Destinations::Marc` (PR#138)
 * `Destinations::Lambda` (PR#139)
@@ -78,32 +93,29 @@ These changes are merged into the `main` branch, but have not been released. Aft
 * Job duration report (added to normal and verbose job run) (PR#154, PR#157)
 * `IterativeCleanup` mixin (PR#180)
 
-=== Changed
+==== Changed
 * Transforms that take an `action` argument now mix in the new `ActionArgumentable` module and validate the argument values in a consistent way (PR#138)
 * Name and role term values extracted from MARC data by subclasses of `Transforms::Marc::ExtractBaseNameData` are run through `Utils::MarcNameCleaner` and `Utils::MarcRoleTermCleaner` (PR#141)
 * `Fingerprint::Add` now passes in default delim: U+241F / E2 90 9F / Symbol for Unit Separator (PR#155)
 * `Fingerprint::Decode` now passes in default delim (U+241F / E2 90 9F / Symbol for Unit Separator), and default prefix (fp) (PR#155)
 * `Fingerprint::FlagChanged` can now be passed an `ignore_fields` parameter indicating fields included in the fingerprint, but which should not be compared to current values and flagged (PR#168)
-=== Bugfixes
+
+==== Bugfixes
 * Fixes https://github.com/lyrasis/kiba-extend/issues/146[#46 - CombineValues::FullRecord with multi-sources can result in different values] (PR#147)
 * Fixes issue where job registry entry with a Marc source and CSV destination could not be used as a source or lookup in jobs (PR#137)
 * Fixes issue in `StringValue::ToArray` transform where delim=nil was not correctly being calculated (PR#145)
 * Fixes https://github.com/lyrasis/kiba-extend/issues/152[#152]: Fingerprint::Decode error: Encoding::CompatibilityError: incompatible character encodings: ASCII-8BIT and UTF-8 (PR#153)
 * Fixes https://github.com/lyrasis/kiba-extend/issues/162[#162]: failure of `Delete::EmptyFields` transform when passed a source with no rows
 * Fixes https://github.com/lyrasis/kiba-extend/issues/179[#179]: renaming field with same fieldname in `from` and `to` resulted in the field being deleted (PR#181)
 
-=== Deleted
-
-=== Deprecated/Will break in a future version
+==== Deprecated/Will break in a future version
 * `sep` parameter will be replaced by `delim` in `CombineValues::FromFieldWithDelimiter` and `CombineValues::FullRecord` (PR#147)
 
-=== Dev
+==== Dev
 * Adds `Kiba::Extend::ErrMod` module to be included into `Kiba::Extend`-specific error classes. This allows us to subclass each application-specific error to the semantically appropriate Ruby exception class, while retaining the ability to identify/scope/rescue only application-specific errors. (PR#138)
 * Add `:info` method to `Kiba::Extend::ErrMod` module, to print error type, message, and backtrace to STDOUT in a consistent way. (PR#141)
 * Set up https://github.com/standardrb/standard[standardrb] linting, with Kristina's standard (ha) minor overrides (PR#169)
 
-== Releases
-
 === 3.3.0 - 2023-02-17
 
 ==== Added

Gemfile.lock

@@ -12,7 +12,7 @@ GIT
 PATH
   remote: .
   specs:
-    kiba-extend (3.3.0)
+    kiba-extend (4.0.0)
       activesupport (>= 6, < 8)
       amazing_print (~> 1.4)
       csv (~> 3)

doc/iterative_cleanup.md

@@ -1,4 +1,4 @@
-# Using the iterative cleanup mixin
+# Using the `IterativeCleanup` mixin (added in v4.0.0)
 
 "Iterative cleanup" means the client may provide the worksheet more
 than once, or that you may need to produce a fresh worksheet for the

lib/kiba/extend.rb

@@ -87,6 +87,7 @@ def reload!
 
     # Ruby modules that serve as namespaces under which config
     #   modules for a project are nested.
+    # @since 4.0.0
     # @note You must set this from
     #   an individual project if you wish to use the
     #   {Kiba::Extend::Mixins::IterativeCleanup} mixin.
@@ -246,6 +247,7 @@ def reload!
     # List of config modules in project namespaces set in {config_namespaces}
     #   setting
     #
+    # @since 4.0.0
     # @return [Array<Module>]
     def project_configs
       config_namespaces.map { |ns| get_config_mods(ns, ns.constants) }
@@ -255,40 +257,13 @@ def project_configs
 
     # @param ns [Module]
     # @param constants [Array<Symbol>]
+    # @since 4.0.0
     # @return [Array<Module>]
     def get_config_mods(ns, constants)
       constants.map { |const| ns.const_get(const) }
     end
     private_class_method :get_config_mods
 
-    # The section below is for backward comapatibility only
-
-    # @since 3.2.1
-    # Warns that nested job config settings will be deprecated and gives new
-    #   setting to use
-    def warn_unnested(name, value)
-      rep_by = "job_#{name}"
-      msg = "Kiba::Extend.config.job.#{name} setting has been replaced by "\
-        "Kiba::Extend.config.#{rep_by}"
-      warn("#{Kiba::Extend.warning_label}: #{msg}")
-      value
-    end
-
-    setting :job, reader: true do
-      setting :show_me, default: Kiba::Extend.job_show_me, reader: true,
-        constructor: proc { |name, value|
-                       Kiba::Extend.warn_unnested(name, value)
-                     }
-      setting :tell_me, default: Kiba::Extend.job_tell_me, reader: true,
-        constructor: proc { |name, value|
-                       Kiba::Extend.warn_unnested(name, value)
-                     }
-      setting :verbosity, default: Kiba::Extend.job_verbosity, reader: true,
-        constructor: proc { |name, value|
-                       Kiba::Extend.warn_unnested(name, value)
-                     }
-    end
-
     # Strips, collapses multiple spaces, removes terminal commas, strips again
     # removes "NULL"/treats as nilValue
     CSV::Converters[:stripplus] = lambda { |s|

lib/kiba/extend/destinations/destinationable.rb

@@ -5,6 +5,8 @@ module Extend
     module Destinations
       # Mix-in module for extending destinations so they can be set up in
       #   jobs
+      #
+      # @since 4.0.0
       module Destinationable
         include Kiba::Extend::Registry::Fileable
         # @return Constant if there is a {Kiba::Extend::Sources} class

lib/kiba/extend/destinations/lambda.rb

@@ -4,6 +4,8 @@ module Kiba
   module Extend
     module Destinations
       # Wrapper around `Kiba::Common::Destinations::Lambda`
+      #
+      # @since 4.0.0
       class Lambda < Kiba::Common::Destinations::Lambda
         extend Destinationable
 

lib/kiba/extend/destinations/marc.rb

@@ -10,6 +10,8 @@ module Destinations
       # This is a wrapper around `ruby-marc`'s `MARC::Writer`, so see
       #   relevant documentation in:
       #   https://github.com/ruby-marc/ruby-marc/blob/main/lib/marc/writer.rb
+      #
+      # @since 4.0.0
       class Marc
         extend Destinationable
 

lib/kiba/extend/job.rb

@@ -11,6 +11,8 @@ module Job
       #   job results in 1 or more rows being written
       # @return [false] if jobkey is not defined, or if job results in 0 rows
       #   when run
+      #
+      # @since 4.0.0
       def output?(jobkey)
         begin
           reg = Kiba::Extend.registry.resolve(jobkey)

lib/kiba/extend/jobs/base_job.rb

@@ -23,7 +23,7 @@ class BaseJob
         # @param mode [:run, :setup, :info] :info mode sets up files only.
         #   :setup mode sets up files and handles requirements, including
         #   running any necessary jobs to create sources and/or lookups needed
-        #   by the job. :run does all of the above and runs the job.
+        #   by the job. :run does all of the above and runs the job. Since 4.0.0
         def initialize(files:, transformer:, mode: :run)
           if caller(2, 5).join(" ")["block in handle_requirements"]
             @dependency = true

lib/kiba/extend/jobs/json_to_csv_job.rb

@@ -6,6 +6,8 @@ module Jobs
       # Job taking a JSON source that yields `Hash`es, and writing
       #   to a CSV (or other tabular) destination expecting the same
       #   headers/fields in every row
+      #
+      # @since 4.0.0
       class JsonToCsvJob < BaseJob
         private
 

lib/kiba/extend/mixins/iterative_cleanup.rb

@@ -2,6 +2,8 @@
 
 # Mixin module for setting up iterative cleanup based on a source table.
 #
+# @since 4.0.0
+#
 # "Iterative cleanup" means the client may provide the worksheet more
 #   than once, or that you may need to produce a fresh worksheet for
 #   the client after a new database export is provided.

lib/kiba/extend/registry/fileable.rb

@@ -4,6 +4,8 @@ module Kiba
   module Extend
     module Registry
       # Mix-in module with shared methods for sources and destinations
+      #
+      # @since 4.0.0
       module Fileable
         # @param path [String, nil]
         def default_args(path = nil)

lib/kiba/extend/sources/csv.rb

@@ -5,6 +5,8 @@ module Extend
     module Sources
       # Extension of `Kiba::Common::Sources::CSV`, adding methods that support
       #   use as a source in registry entries
+      #
+      # @since 4.0.0
       class CSV < Kiba::Common::Sources::CSV
         extend Lookupable
         extend Sourceable

lib/kiba/extend/sources/enumerable.rb

@@ -5,6 +5,8 @@ module Extend
     module Sources
       # Extension of `Kiba::Common::Sources::Enumerable`, adding methods
       #   supporting use as a source in registry entries
+      #
+      # @since 4.0.0
       class Enumerable < Kiba::Common::Sources::Enumerable
         extend Sourceable
 

lib/kiba/extend/sources/json_dir.rb

@@ -44,6 +44,8 @@ module Sources
       #   destination will protect against these errors.
       #   {Kiba::Extend::Jobs::JsonToCsvJob} runs this transform automatically
       #   as the last step before writing out rows
+      #
+      # @since 4.0.0
       class JsonDir
         extend Sourceable
 

lib/kiba/extend/sources/lookupable.rb

@@ -5,6 +5,8 @@ module Extend
     module Sources
       # Mix-in module for extending sources so that they can be used
       #   (or not) as lookups in jobs
+      #
+      # @since 4.0.0
       module Lookupable
         # @return True
         def is_lookupable?

lib/kiba/extend/sources/sourceable.rb

@@ -5,6 +5,8 @@ module Extend
     module Sources
       # Mix-in module for extending sources so they can be used as sources
       #   in jobs
+      #
+      # @since 4.0.0
       module Sourceable
         include Kiba::Extend::Registry::Fileable
 

lib/kiba/extend/transforms/action_argumentable.rb

@@ -4,6 +4,8 @@ module Kiba
   module Extend
     module Transforms
       # Mixin module providing consistent validation of `action` argument
+      #
+      # @since 4.0.0
       module ActionArgumentable
         ::ActionArgumentable = Kiba::Extend::Transforms::ActionArgumentable
 

lib/kiba/extend/transforms/clean/ensure_consistent_fields.rb

@@ -27,6 +27,8 @@ module Clean
         #     {foo: nil, bar: nil, baz: 'baz', boo: 'boo'}
         #   ]
         #   expect(result).to eq(expected)
+        #
+        # @since 4.0.0
         class EnsureConsistentFields
           def initialize
             @keys = {}

lib/kiba/extend/transforms/combine_values/from_fields_with_delimiter.rb

@@ -68,10 +68,10 @@ module CombineValues
         #   ]
         #   expect(result).to eq(expected)
         class FromFieldsWithDelimiter
-          include Allable
+          include Allable # since 4.0.0
           include SepDeprecatable
 
-          # @param sources [Array<Symbol>] Fields whose values are to be
+          # @param sources [Array<Symbol>, :all] Fields whose values are to be
           #   combined
           # @param target [Symbol] Field into which the combined value will be
           #   written. May be one of the source fields
@@ -80,11 +80,12 @@ class FromFieldsWithDelimiter
           # @param delim [String] Value used to separate individual field values
           #   in combined target field
           # @param prepend_source_field_name [Boolean] Whether to insert the
-          #   source field name before its value in the combined value.
+          #   source field name before its value in the combined value. Since
+          #   4.0.0
           # @param delete_sources [Boolean] Whether to delete the source fields
           #   after combining their values into the target field. If target
           #   field name is the same as one of the source fields, the target
-          #   field is not deleted.
+          #   field is not deleted. Since 4.0.0
           def initialize(sources: :all, target: :index, sep: nil, delim: nil,
             prepend_source_field_name: false, delete_sources: true)
             @fields = [sources].flatten

lib/kiba/extend/transforms/delete/fieldnames_starting_with.rb

@@ -27,6 +27,8 @@ module Delete
         #      changed: nil},
         #   ]
         #   expect(result).to eq(expected)
+        #
+        # @since 4.0.0
         class FieldnamesStartingWith
           # @param prefix [String] if a fieldname begins with or equals this
           #   string, the field will be deleted

lib/kiba/extend/transforms/explode/rows_from_grouped_multival_fields.rb

@@ -121,6 +121,7 @@ module Explode
         #     {id: "8", name: nil, role: nil}
         #   ]
         #   expect(result).to eq(expected)
+        # @since 4.0.0
         class RowsFromGroupedMultivalFields
           # @param fields [Symbol] the grouped fields from which rows will be
           #   created

lib/kiba/extend/transforms/fingerprint/flag_changed.rb

@@ -140,6 +140,8 @@ class FlagChanged
           #   fingerprint that should NOT compared/flagged
           # @param empty_equals_nil [Boolean] whether to treat blank and nil
           #   values as equal
+          #
+          # @since 4.0.0
           def initialize(fingerprint:, source_fields:, target:, delim: "␟",
             prefix: "fp", delete_fp: false, ignore_fields: [],
             empty_equals_nil: true)

lib/kiba/extend/transforms/fingerprint/merge_corrected.rb

@@ -119,6 +119,8 @@ module Fingerprint
         #     {fp: "4", a: 'ant', b: 'bear', corr: "n"},
         #   ]
         #   expect(result).to eq(expected)
+        #
+        # @since 4.0.0
         class MergeCorrected
           # @param keycolumn [Symbol] the name of the field containing
           #   fingerprint values in data into which corrections will be

lib/kiba/extend/transforms/helpers/org_name_checker.rb

@@ -10,6 +10,8 @@ module Helpers
         #   on freetext, be wary of false positives (though the patterns and
         #   the duplicative anchoring matching tries to avoid matching
         #   subject-like terms
+        #
+        # @since 4.0.0
         class OrgNameChecker
           class << self
             def call(

lib/kiba/extend/transforms/helpers/person_name_checker.rb

@@ -19,6 +19,8 @@ module Helpers
         #   set at https://www.ssa.gov/OACT/babynames/limits.html which have
         #   been on more than 100 Social Security card applications from
         #   1880-2022. So there is a definite U.S. bias.
+        #
+        # @since 4.0.0
         class PersonNameChecker
           class << self
             def call(

lib/kiba/extend/transforms/marc/extract_meeting_name_data.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# rubocop:todo Layout/LineLength
-
 require "marc"
 
 module Kiba
@@ -13,7 +11,8 @@ module Marc
         #
         # @example
         #   # =001  008000714-7
-        #   # =711  2\$aAssociation of Child Psychology Annual Conference.$esponsor$evenue
+        #   # =711  2\$aAssociation of Child Psychology Annual Conference.
+        #   #          $esponsor$evenue
         #   rec = get_marc_record(index: 6)
         #   xform = Marc::ExtractMeetingNameData.new
         #   results = []
@@ -24,6 +23,8 @@ module Marc
         #          :nametype=>"meeting", :role_code=>"",
         #          :role_term=>"sponsor|venue", :marcid=>"008000714-7"}
         #   expect(results.first).to eq(row)
+        #
+        # @since 4.0.0
         class ExtractMeetingNameData < ExtractBaseNameData
           # @param name_type [String] to insert into name_type_target field
           # @param name_fields [Array<String>] MARC fields from which name data
@@ -49,4 +50,3 @@ def initialize(name_type: "meeting",
     end
   end
 end
-# rubocop:enable Layout/LineLength