diff --git a/CHANGELOG.md b/CHANGELOG.md
index 634962ac..3fb069a2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,10 @@ Please visit [cucumber/CONTRIBUTING.md](https://github.com/cucumber/cucumber/blo
 ## [Unreleased]
 
 ## [17.0.0] - 2026-06-01
+### Removed
+- Strict configuration has been removed from all `Result` classes
+- Removed the ability to list event attributes (Only the `#to_h` method now remains for this purpose)
+
 ### Added
 - Added `#to_envelope` for `Cucumber::Core::Gherkin::Document` ([#329](https://github.com/cucumber/cucumber-ruby-core/pull/329))
 
@@ -23,10 +27,6 @@ Please visit [cucumber/CONTRIBUTING.md](https://github.com/cucumber/cucumber/blo
 - Change to use worst Test Step result as the Test Case result
 ([#317](https://github.com/cucumber/cucumber-ruby-core/pull/317))
 
-### Removed
-- Strict configuration has been removed from all `Result` classes
-- Removed the ability to list event attributes (Only the `#to_h` method now remains for this purpose)
-
 ## [16.2.0] - 2026-02-06
 ### Changed
 - Added the test result type 'ambiguous'
@@ -42,12 +42,12 @@ Please visit [cucumber/CONTRIBUTING.md](https://github.com/cucumber/cucumber/blo
 - Further bumped the lower bounds of messages and gherkin several more versions
 
 ## [16.0.0] - 2025-12-16
-### Changed
-- Bumped the lower bounds of messages to v28, gherkin to v33 and tag-expressions to v6
-
 ### Removed
 - Remove support for ruby 3.1 and below. 3.2 or higher is required now
 
+### Changed
+- Bumped the lower bounds of messages to v28, gherkin to v33 and tag-expressions to v6
+
 ## [15.4.0] - 2025-12-10
 ### Changed
 - Permit usage of gherkin up to v39, messages up to v32
@@ -76,24 +76,25 @@ Please visit [cucumber/CONTRIBUTING.md](https://github.com/cucumber/cucumber/blo
 - Permit usage of gherkin up to v30
 
 ## [15.0.0] - 2024-12-24
+### Removed
+- Remove support for ruby 2.7 and below. 3.0 or higher is required now (Owing to messages bump)
+
 ### Changed
 - Permit usage of messages up to v28
 
 ### Fixed
 - References to the Time Conversion and UUID helpers needed altering to use the `Helpers` namespace
 
-### Removed
-- Remove support for ruby 2.7 and below. 3.0 or higher is required now (Owing to messages bump)
-
 ## [14.0.0] - 2024-08-08
-### Changed
-- Permit usage of gherkin up to v29 and messages up to v26
-- **Internal Breaking Change**: Structure of `Action` classes have changed.
-See upgrading notes for [14.0.0.md](upgrading_notes/14.0.0.md#upgrading-to-cucumber-core-1400)
+### Breaking Change
+- Structure of `Action` classes have changed. See upgrading notes for [14.0.0.md](upgrading_notes/14.0.0.md#upgrading-to-cucumber-core-1400)
 ([#282](https://github.com/cucumber/cucumber-ruby-core/pull/282))
 
 ### Removed
-- Remove support for ruby 2.6 and below. 2.7 or higher is required now (Autofixed to Ruby 2.7 styles)
+- Removed support for ruby 2.6 and below. 2.7 or higher is required now (Autofixed to Ruby 2.7 styles)
+
+### Changed
+- Permit usage of gherkin up to v29 and messages up to v26
 
 ## [13.0.3] - 2024-07-24
 ### Changed
@@ -112,6 +113,9 @@ See upgrading notes for [14.0.0.md](upgrading_notes/14.0.0.md#upgrading-to-cucum
 - The `Cucumber::Core::Test::Result::Passed` class was missing the strict keyword argument handling
 
 ## [13.0.0] - 2023-12-05
+### Removed
+- Remove legacy `unindent` gem (Now no longer required since Ruby 2.3 and Squiggly heredocs) ([#278](https://github.com/cucumber/cucumber-ruby-core/pull/278))
+
 ### Changed
 - Now using a 2-tiered changelog to avoid any bugs when using polyglot-release
 - More refactoring of the repo by fixing up a bunch of manual rubocop offenses (See PR's for details)
@@ -124,9 +128,6 @@ See upgrading notes for [13.0.0.md](upgrading_notes/13.0.0.md#upgrading-to-cucum
 ### Fixed
 - Restore support for matching a scenario by its Feature, Background, and Rule line numbers ([#247](https://github.com/cucumber/cucumber-ruby-core/pull/247))
 
-### Removed
-- Remove legacy `unindent` gem (Now no longer required since Ruby 2.3 and Squiggly heredocs) ([#278](https://github.com/cucumber/cucumber-ruby-core/pull/278))
-
 ## [12.0.0] - 2023-09-06
 ### Changed
 - Update gherkin and messages minimum dependencies
diff --git a/upgrading_notes/17.0.0.md b/upgrading_notes/17.0.0.md
new file mode 100644
index 00000000..b9ddfe8e
--- /dev/null
+++ b/upgrading_notes/17.0.0.md
@@ -0,0 +1,85 @@
+# Upgrading to cucumber-core 17.0.0
+
+## Base Event Class
+
+The previous structure of inheriting from `Cucumber::Core::Event.new(:var1, :var2)` is now considered deprecated
+
+You should now inherit from `Cucumber::Core::Events::Base` and define an initializer that takes the necessary variables. For example:
+
+Whilst this change does involve in writing a little more code, it is much easier to triage and diagnose and has fewer issues on JRuby.
+
+It is worth noting for the downstream consumer. The event will have fewer methods available to it, and will not have the
+`#attributes` defined as methods on the event. Instead, you will need to lean solely on the `#to_h` method to get the attributes of the event.
+This is a more explicit way of getting the attributes and is less prone to issues than in the previous implementation.
+
+### Before cucumber-core 17.0.0
+
+```ruby
+# frozen_string_literal: true
+
+require_relative '../event'
+
+module Cucumber
+  module Core
+    module Events
+      # Signals that a foo event has occurred
+      class FooEvent < Cucumber::Core::Event.new(:bar, :baz)
+      end
+    end
+  end
+end
+```
+
+### With cucumber-core 17.0.0
+
+```ruby
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Cucumber
+  module Core
+    module Events
+      # Signals that a foo event has occurred
+      class FooEvent < Base
+        attr_reader :bar, :baz
+
+        def self.event_id
+          :foo_event
+        end
+
+        def initialize(bar, baz)
+          @bar = bar
+          @baz = baz
+          super()
+        end
+      end
+    end
+  end
+end
+```
+
+## Strict Configuration
+
+All strict configuration has been removed from all `Result` classes. This is a feature that has slowly changed perception over time
+If you were using this feature, you will need to now use the new behaviours which are as follows.
+
+### Before cucumber-core 17.0.0
+
+| Step Category  | Error (Y/N)? |
+|----------------|--------------|
+| undefined step | no error     |
+| pending step   | no error     |
+| failed step    | error        |
+| passed step    | no error     |
+| ambiguous step | error        |
+
+### With cucumber-core 17.0.0
+
+| Step Category  | Error (Y/N)? |
+|----------------|--------------|
+| undefined step | error        |
+| pending step   | error        |
+| failed step    | error        |
+| passed step    | no error     |
+| ambiguous step | error        |