CHANGELOG.md in statsd-instrument-2.4.0 vs CHANGELOG.md in statsd-instrument-2.5.0

@@ -1,15 +1,128 @@
 # Changelog
 
-This file documents the changes between releases of this library. When creating a pull request,
-please at an entry to the "unreleased changes" section below.
+This file documents the changes between releases of this library. When
+creating a pull request, please add an entry to the "unreleased changes"
+section below.
 
 ### Unreleased changes
 
+_Nothing yet_
+
+## Version 2.5.0
+
+- **DEPRECATION**: Providing a sample rate and tags to your metrics and method
+  instrumentation macros should be done using keyword arguments rather than
+  positional arguments. Also, previously you could provide `value` as a keyword
+  argument, but it should be provided as the second positional argument.
+
+  ``` ruby
+  # DEPRECATED
+  StatsD.increment 'counter', 1, 0.1, ['tag']
+  StatsD.increment 'counter', value: 123, tags: { foo: 'bar' }
+  StatsD.measure('duration', nil, 1.0) { foo }
+  statsd_count_success :method, 'metric-name', 0.1
+
+  # SUPPORTED
+  StatsD.increment 'counter', sample_rate: 0.1, tags: ['tag']
+  StatsD.increment 'counter', 123, tags: { foo: 'bar' }
+  StatsD.measure('duration', sample_rate: 1.0) { foo }
+  statsd_count_success :method, 'metric-name', sample_rate: 0.1
+  ```
+
+  The documentation of the methods has been updated to reflect this change.
+  The behavior of the library is not changed for the time being, so you can
+  safely upgrade to this version. However, in a future major release, we will
+  remove support for the positional arguments.
+
+  The library includes some cops to help with finding issues in your existing
+  codebase, and fixing them:
+
+  ``` sh
+  # Check for positional arguments on your StatsD.metric calls
+  rubocop --only StatsD/PositionalArguments \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/positional_arguments.rb
+
+  # Check for positional arguments on your statsd_instrumentation macros
+  rubocop --only StatsD/MetaprogrammingPositionalArguments \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metaprogramming_positional_arguments.rb
+
+  # Check for value as keyword argument
+  rubocop --only StatsD/MetricValueKeywordArgument \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metric_value_keyword_argument.rb
+
+  ```
+
+- **DEPRECATION**: Relying on the return value of the StatsD metric methods
+  (e.g. `StatsD.increment`) is deprecated. StatsD is a fire-and-forget
+  protocol, so your code should not depend on the return value of these methods.
+
+  The documentation of the methods has been updated to reflect this change.
+  The behavior of the library is not changed for the time being, so you can
+  safely upgrade to this version. However, in a future major release, we will
+  start to explicitly return `nil`.
+
+  This gem comes with a Rubocop rule that can help verify that your
+  application is not relying on the return value of the metric methods. To use
+  this cop on your codebase, invoke Rubocop with the following arguments:
+
+  ``` sh
+  rubocop --only StatsD/MetricReturnValue \
+    -r `bundle show statsd-instrument`/lib/statsd/instrument/rubocop/metric_return_value.rb
+  ```
+
+- **Strict mode**: These custom Rubocop rules will give you a quick indication
+  of the issues in your codebase, but are not airtight. This library now also
+  ships with strict mode, a mixin module that already disables this deprecated
+  behavior so it will raise exceptions if you are depending on deprecated
+  behavior. It will also do additional input validation, and make sure the
+  `StatsD` metric methods return `nil`.
+
+  You enable strict mode by requiring `statsd/instrument/strict`:
+
+  ``` ruby
+  # In your Gemfile
+  gem 'statd-instrument', require: 'statsd/instrument/strict'
+
+  # Or, in your test helper:
+  require 'statsd/instrument/strict'
+  ```
+
+  It is recommended to enable this in CI to find deprecation issues, but not
+  in production because enabling it comes with a performance penalty.
+
+- **Performance improvements 🎉**: Several internal changes have made the
+  library run singificantly faster. The changes:
+
+  - Improve performance of duration calculations. (#168)
+  - Early exit when no changes are needed to bring tags and metric names to
+    normalized form. (#173)
+  - Refactor method argument handling to reduce object allocations and
+    processing. (#174)
+
+  A benchmark suite was added (#169) and it now runs as part of CI (#170) so we
+  can more easily spot performance regressions before they get merged into the
+  library.
+
+  The result of this work:
+
+  ```
+  Comparison:
+  StatsD metrics to local UDP receiver (branch: master, sha: 2f98046):    10344.9 i/s
+  StatsD metrics to local UDP receiver (branch: v2.4.0, sha: 371d22a):     8556.5 i/s - 1.21x  (± 0.00) slower
+  ```
+
+  The deprecations mentioned above will allows us to provide an even greater
+  performance improvement, so update your code base to not use those
+  deprecations anymore, and keep your eyes open for future releases of the
+  library!
+
+- _Bugfix:_ avoid deadlock when an error occurs in the integration test suite (#175)
+
 ## Version 2.4.0
 
 - Add `StatsD.default_tags` to specify tags that should be included in all metrics. (#159)
-- Improve assertion message when assertying metrics whose tags do not match. (#100)
+- Improve assertion message when asserting metrics whose tags do not match. (#100)
 - Enforce the Shopify Ruby style guide. (#164)
 - Migrate CI to Github actions. (#158)
 - Make the library frozen string literal-compatible. (#161, #163)
 - Fix all Ruby warnings. (#162)