WIP: Add a few notes about the new changelog

CHANGELOG-10.md

@@ -0,0 +1,164 @@
+---
+icon: versions-24
+---
+
+# CHANGELOG
+
+## Release Policy
+
+Pagy follows the [Semantic Versioning 2.0.0](https://semver.org/), and introduces BREAKING CHANGES only for MAYOR versions.
+
+We release any new version (MAJOR, MINOR, PATCH) as soon as it is ready for release, regardless of any time constraint, frequency
+or duration.
+
+We rarely deprecate elements (releasing a new MAYOR version is just simpler and more efficient). However, when we do, you can
+expect the old/deprecated functionality to be supported ONLY during the current MAYOR version.
+
+## Recommended Version Constraint
+
+Given a version number `MAJOR.MINOR.PATCH` (e.g. `10.0.0`):
+
+The `gem 'pagy', '~> 10.0'` Gemfile entry (without the PATCH number) ensures that the `bundle update` command will update pagy to
+the most recent version WITHOUT BREAKING CHANGES.
+
+Increment the MAYOR version in your Gemfile ONLY when you are ready to handle the BREAKING CHANGES.
+
+## Breaking Changes
+
+If you upgrade from version `< 10.0.0` see the following:
+
+- [Breaking changes in version 10.0.0](#version-1000)
+- [Breaking changes in version 9.0.0](CHANGELOG_LEGACY.md#version-900)
+- [Breaking changes in version 8.0.0](CHANGELOG_LEGACY.md#version-800)
+- [Breaking changes in version 7.0.0](CHANGELOG_LEGACY.md#version-700)
+- [Breaking changes in version 6.0.0](CHANGELOG_LEGACY.md#version-600)
+- [Breaking changes in version 5.0.0](CHANGELOG_LEGACY.md#version-500)
+- [Breaking changes in version 4.0.0](CHANGELOG_LEGACY.md#version-400)
+- [Breaking changes in version 3.0.0](CHANGELOG_LEGACY.md#version-300)
+- [Breaking changes in version 2.0.0](CHANGELOG_LEGACY.md#version-200)
+- [Breaking changes in version 1.0.0](CHANGELOG_LEGACY.md#version-100)
+
+## Deprecations
+
+None
+
+<hr>
+
+## Version 10.0.0
+
+### Overview
+
+This is a mayor, MAYOR version, with important additions and improvements, even easier to use and customize, with a brand-new
+documentation and the new `Pagy AI`, ready to answer your questions.
+
+### Keynav Pagination Addition
+
+{ Add the summary of the Keynav doc, citing the advantages (e.g. fast as keyset but navigable) and the fallback on the pagy
+countless, for browser that don't support SessionStorage}
+
+### Improvements
+
+- Automatic loading of just the code that you use
+  : All the classes, modules and helpers are automatically loaded only if you actually use them, without any explicit `require`.
+  _(the legacy version was loading more code by default)_
+
+- Better file and namespace system organization
+  : The class hierarchy, the inheritance of `DEFAULT`, the mixin files and the test file structure have been deeply reorganized.
+  : The code is cleaner, more concise and more readable, with fewer modules in the `ancestors` array.
+
+- The extras are almost all gone
+  : They have been converted to autoloaded mixins, or integrated in the core code. You can use the methods that you need, and they
+  will just work without explicit requiring.
+  : The only extras that are left _(for different reasons)_ are: `gearbox`, `i18n` and `size`. They must be required in the
+  initializer as usual in order to work.
+
+- The Pagy::Countless remembers the last page
+  : When you jump back in the page nav, it remembers the current page count, so you can jump forward.
+
+- URLs are cleaner
+  : No more empty params or extra '?' in the url string
+  : URL templates are safer for string manipulation.
+  : The `pagy_page_url` (legacy `pagy_url_for`) can be used also without a request (incorporating the legacy `standalone` extra)
+
+- Javascript refactoring
+  : Updated the support for the pagy helpers and keynav pagination.
+  : Added the plain `pagy.js` and relative source map.
+
+### Breaking Changes
+
+#### Core Code Changes
+
+- The `:params` variable set to a lambda should modify the passed `query_params` directly: the returned value is now ignored _(
+better performance)_
+
+- Direct instantiation of the pagy constructor classes is not recommended.
+  : Use the provided constructor helpers for easier usage, maintenance and forward compatibility.
+
+#### Simple renaming (without logic changes)
+
+| Type        | Search         | Replace         | Notes                                                |
+|-------------|----------------|-----------------|------------------------------------------------------|
+| Constructor | `pagy(`        | `pagy_offset(`  | For symmetry with the other old and new constructors |
+| Method      | `pagy_url_for` | `pagy_page_url` | It was causing rails-related expectations            |
+
+#### Extras Replacement
+
+##### `arel`, `array`, `boostrap`, `bulma`, `calendar`, `countless`, `hesders`, `keyset`, `pagy`
+
+- Just remove the `require 'pagy/extras/<extra-name>'` from the initializer.
+
+##### `elasticsearch_rails`, `meilisearch`, `searchkick`
+
+- Remove the `require 'pagy/extras/<extra-name>'` from the initializer
+- Replace your existing (if any) `Pagy.new_from_<extra-name>` with `pagy_<extra-name>`. _(Active and passive modes are now handled
+  by the same helper.)_
+- Replace the existing (if any) `extend Pagy::Search` statement in your model with `extend Pagy::Offset::Search`.
+- The `YourModule.pagy_search` name customization has been discontinued. Remove the existing (if any) `:<extra-name>_pagy_search`
+  variable from your code, and use the original `pagy_search` method.
+- Rename the existing (if any) `:<extra-name>_search` variable as `:search_method`.
+
+##### `jsonapi`
+
+- Remove the `require 'pagy/extras/jsonapi'` from the initializer.
+- You should use the `:jsonapi` variable to trigger the feature.
+- Its default switched from out-out (`true` by default) to opt-in (`false` by default) now.
+- Add `Pagy::DEFAULT[:jsonapi] = true` to your initializer, if you want to trigger the same opt-out default behavior provided by
+  the extra.
+
+##### `limit`
+
+- Remove the `require 'pagy/extras/limit'` from the initializer.
+- Replace the `:limit_extra` variable with `:limit_requestable`.
+- You should use the `:limit_requestable` variable to trigger the feature.
+- Its default switched from out-out (`true` by default) to opt-in (`false` by default) now.
+- Add `Pagy::DEFAULT[:limit_requestable] = true` to your initializer, if you want to trigger the same opt-out default behavior
+  provided by the extra.
+
+##### `metadata`
+
+- Remove the `require 'pagy/extras/metadata'` from the initializer.
+- Rename the existing (if any) `:scaffold_url` to `url_template`
+
+##### `overflow`
+
+- Remove the `require 'pagy/extras/overflow'` from the initializer.
+- You should use the `:overflow` variable to trigger the feature.
+- Its default switched from out-out (`:empty_page` by default) to disabled now.
+- Add `Pagy::DEFAULT[:overflow] = empty_page` to your initializer, if you want to trigger the same opt-out default behavior
+  provided by the extra.
+
+##### `trim` (discontinued)
+
+- It was almost useless and half backed, causing a lot of complications in the ruby and javascript code.
+- Use a proper way to address your requirement, like using URL rewriting at the HTTP server level.
+
+##### `gearbox`, `i18n`, `size`
+
+- They are still extras, no changes is required to keep using them.
+
+#### Possibly Breaking Overridings
+
+- The internal Pagy protected methods have been renamed and refactored. If you use custom Pagy classes, you may need to search
+  into the code.
+
+[LEGACY CHANGELOG >>>](CHANGELOG_LEGACY.md)