WIP: Add a few notes about the new changelog

Author: ddnexus

CHANGELOG-10.md

@@ -0,0 +1,175 @@
+---
+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, a lot easier to use and customize, it has fewer methods
+and variables, cleaner code with a brand-new documentation and the new `Pagy AI`, ready to answer your questions.
+
+### Keynav Pagination Addition
+
+The pagy exclusive technique to use `keyset pagination with numeric pages, supporting `pagy_*navs` and other Frontend
+helpers.<br/>The best technique for performance AND functionality!
+
+### Improvements
+
+- Automatic loading of just the code that you actually use
+  : Every class, module and helper is automatically loaded only if you actually use it, without any explicit `require`.
+  _(the legacy version was requiring more code)_
+
+- Better file and namespace system organization
+  : The class hierarchy, the mixin files, and the test file structure have been deeply reorganized.
+  : The code is cleaner, more concise and more readable, adding fewer modules in the `ancestors` array of yur app.
+
+- The extras are almost all gone
+  : They have been converted to autoloaded mixins, or integrated in the core code at zero-cost. You can use the methods that you
+  need, and they will just work without explicit requiring.
+  : The only extras that are left _(for different compelling reasons)_ are: `gearbox`, `i18n` and `size`. They must be required in
+  the initializer as usual.
+
+- 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.
+
+- Cleaner URLs
+  : 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 Changes
+
+- The `Pagy::DEFAULT` is now frozen.
+  : Remove all the `Pagy::DEFAULT` variables from your code and pass their variables to the constructor. As an alternative to
+  avoid repetitions, define your own `PAGY_DEFAULT = {...}` hash and pass it to the different constructors:
+  `pagy_offset(scope, **PAGY_DEFAULT, ...)`
+
+- Direct instantiation of the pagy constructor classes is not recommended.
+  : Use the provided constructor helpers for easier usage, maintenance and forward compatibility.
+
+- Replace the existing (if any) `Pagy.root` with `Pagy::ROOT`
+- When the `:params` variable is set to a lambda, it should modify the passed `query_params` directly. The returned value is now
+  ignored for a sligtly better performance.
+
+#### Simple renaming (without logic changes)
+
+| Type        | Search         | Replace         | Notes                                                    |
+|-------------|----------------|-----------------|----------------------------------------------------------|
+| Constructor | `pagy(`        | `pagy_offset(`  | For consistency with the other old and new constructors  |
+| Method      | `pagy_url_for` | `pagy_page_url` | The legacy naming was causing rails-related expectations |
+
+#### Extras Replacement
+
+##### `arel`, `array`, `boostrap`, `bulma`, `calendar`, `countless`, `headers`, `keyset`, `pagy`
+
+- Just remove the `require 'pagy/extras/<extra-name>'` from the initializer, and continue to use their features without changes.
+
+##### `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 models with `extend Pagy::Offset::Search`.
+- The `pagy_search` name customization has been discontinued. Remove the existing (if any) `:<extra-name>_pagy_search`
+  variable from your code, and use the standard `pagy_search` method.
+- Rename the existing (if any) `:<extra-name>_search` variable as `:search_method` and pass it to the constructor.
+
+##### `jsonapi`
+
+- Remove the `require 'pagy/extras/jsonapi'` from the initializer.
+- Rename `pagy_jsonapi_links` as `pagy_links`. Notice that the `nil` links are now removed as the `JSON:API`
+  requires.
+- You should pass the `:jsonapi` variable to the constructor when you want to trigger the feature.
+
+##### `limit`
+
+- Remove the `require 'pagy/extras/limit'` from the initializer.
+- You should pass the `:maxable_limit` variable - set to the max limit allowed - to the constructor when you want to trigger the
+  feature.
+
+##### `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 pass the `:overflow: ...` variable to the constructor when you want to trigger the feature.
+
+#### `standlone`
+
+- Remove the `require 'pagy/extras/standalone'` from the initializer.
+- Replace the `:url` variable with `:request`, and its content with `{ url_prefix: 'the-previous-value-of-url' }`. You can also
+  optionally add your `query_params` hash. For example `{ query_params: { param1: 'abc', param2: 'def' }` for complete control
+  over the generated url.
+
+##### `trim` (discontinued)
+
+- It was mostly 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`
+
+- Remove the `:gearbox_extra` variable from your code
+- You should pass the `gearbox_limit: [...]` variable to the constructor when you want to trigger the feature.
+
+##### `i18n`, `size`
+
+- No change required.
+
+#### 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)

docs/api/keyset_for_ui.md renamed to docs/api/keynav.md

@@ -31,13 +31,13 @@ You should also familiarize with the [Pagy::Keyset](keyset.md) class.
 
 ## Glossary
 
-This section integrates the [Keyset Glossary](keyset_for_ui.md#glossary)
+This section integrates the [Keyset Glossary](keynav#glossary)
 
-| Term                          | Description                                                                                                                                                                               |
-|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `keyset augmented pagination` | The pagy exclusive technique to use `keyset pagination` with numeric pages, supporting `pagy_*navs` and other Frontend helpers.<br/>The best technique for performance AND functionality! |
-| `page`                        | The array of variables from the client prepared by the `keyset_for_ui` extra, to paginate the requested page.                                                                             |
-| `cutoffs`                     | The array of `cutoff`s of the known pagination state, used to keep track of the visited pages during the navigation. They are cached in the `sessionStorge` of the client.                |
+| Term                | Description                                                                                                                                                                               |
+|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `keynav pagination` | The pagy exclusive technique to use `keyset pagination` with numeric pages, supporting `pagy_*navs` and other Frontend helpers.<br/>The best technique for performance AND functionality! |
+| `page`              | The array of variables from the client prepared by the `keyset_for_ui` extra, to paginate the requested page.                                                                             |
+| `cutoffs`           | The array of `cutoff`s of the known pagination state, used to keep track of the visited pages during the navigation. They are cached in the `sessionStorge` of the client.                |
 
 ## How Pagy Keyset For UI works
 

docs/extras/keyset_for_ui.md

@@ -17,9 +17,9 @@ and other Frontend helpers.
 
 ## Overview
 
-This is a wrapper around the [Pagy::Keyset::Keynav API](/docs/api/keyset_for_ui.md). Please refer to the following resources:
+This is a wrapper around the [Pagy::Keyset::Keynav API](/docs/api/keynav). Please refer to the following resources:
 
-[!ref Keyset For UI: Documentation](/docs/api/keyset_for_ui.md)
+[!ref Keyset For UI: Documentation](/docs/api/keynav)
 
 [!ref Keyset Pagination: Concepts and Overview](/docs/api/keyset.md)
 

gem/apps/demo.ru

@@ -46,20 +46,18 @@ STYLES = { pagy:        { extra: 'pagy', prefix: '', css_anchor: 'pagy-scss' },
 # Sinatra setup
 require 'sinatra/base'
 
-# Pagy initializer
-Pagy::DEFAULT[:limit_requestable] = true
-
 # Sinatra application
 class PagyDemo < Sinatra::Base
   include Pagy::Backend
+  PAGY_DEFAULT = { maxable_limit: 100 }.freeze
 
   get '/' do
     redirect '/pagy'
   end
 
   get '/template' do
     collection = MockCollection.new
-    @pagy, @records = pagy_offset(collection)
+    @pagy, @records = pagy_offset(collection, **PAGY_DEFAULT)
 
     erb :template, locals: { pagy: @pagy, style: 'pagy' }
   end
@@ -85,7 +83,7 @@ class PagyDemo < Sinatra::Base
 
     get("/#{style}") do
       collection = MockCollection.new
-      @pagy, @records = pagy_offset(collection)
+      @pagy, @records = pagy_offset(collection, **PAGY_DEFAULT)
 
       erb :helpers, locals: { style:, prefix: }
     end

gem/apps/keynav.ru

@@ -30,15 +30,12 @@ gemfile(ENV['PAGY_INSTALL_BUNDLE'] == 'true') do
   gem 'sqlite3'
 end
 
-# Pagy initializer
-Pagy::DEFAULT[:limit]             = 4
-Pagy::DEFAULT[:limit_requestable] = true
-
 # Sinatra setup
 require 'sinatra/base'
 # Sinatra application
 class PagyKeynav < Sinatra::Base
   include Pagy::Backend
+  PAGY_DEFAULT = { limit: 4, maxable_limit: 100 }.freeze
 
   get('/javascripts/:file') do
     format = params[:file].split('.').last
@@ -54,9 +51,9 @@ class PagyKeynav < Sinatra::Base
   get '/' do
     Time.zone = 'UTC'
 
-    @order = { animal: :asc, name: :asc, birthdate: :desc, id: :asc }
-    @pagy, @pets = pagy_keynav_js(Pet.order(@order))
-    @ids = @pets.pluck(:id)
+    @order       = { animal: :asc, name: :asc, birthdate: :desc, id: :asc }
+    @pagy, @pets = pagy_keynav_js(Pet.order(@order), **PAGY_DEFAULT)
+    @ids         = @pets.pluck(:id)
     erb :main
   end
 
@@ -164,10 +161,10 @@ require 'active_record'
 # ActiveSupport::JSON::Encoding.time_precision = 6
 
 # Log
-output = ENV['APP_ENV'].equal?('showcase') ? IO::NULL : $stdout
+output                    = ENV['APP_ENV'].equal?('showcase') ? IO::NULL : $stdout
 ActiveRecord::Base.logger = Logger.new(output)
 # SQLite DB files
-dir = ENV['APP_ENV'].equal?('development') ? '.' : Dir.pwd  # app dir in dev or pwd otherwise
+dir = ENV['APP_ENV'].equal?('development') ? '.' : Dir.pwd # app dir in dev or pwd otherwise
 abort "ERROR: Cannot create DB files: the directory #{dir.inspect} is not writable." \
       unless File.writable?(dir)
 # Connection

gem/apps/keyset.ru

@@ -30,15 +30,13 @@ gemfile(ENV['PAGY_INSTALL_BUNDLE'] == 'true') do
   gem 'sqlite3'
 end
 
-# Pagy initializer
-Pagy::DEFAULT[:limit]             = 10
-Pagy::DEFAULT[:limit_requestable] = true
-
 # Sinatra setup
 require 'sinatra/base'
 # Sinatra application
 class PagyKeyset < Sinatra::Base
   include Pagy::Backend
+  PAGY_DEFAULT = { limit: 10, maxable_limit: 100 }.freeze
+
   # Root route/action
   get '/' do
     Time.zone = 'UTC'

gem/apps/keyset_sequel.ru

@@ -30,16 +30,14 @@ gemfile(ENV['PAGY_INSTALL_BUNDLE'] == 'true') do
   gem 'sqlite3'
 end
 
-# Pagy initializer
-Pagy::DEFAULT[:limit]             = 10
-Pagy::DEFAULT[:limit_requestable] = true
-
 # Sinatra setup
 require 'sinatra/base'
 require 'logger'
 # Sinatra application
 class PagyKeysetSequel < Sinatra::Base
   include Pagy::Backend
+  PAGY_DEFAULT = { limit: 10, maxable_limit: 100 }.freeze
+
   # Root route/action
   get '/' do
     @order = { animal: :asc, name: :asc, birthdate: :desc, id: :asc }

gem/apps/rails.ru

@@ -52,17 +52,12 @@ class PagyRails < Rails::Application # :nodoc:
 end
 
 # AR config
-dir = Rails.env.development? ? '.' : Dir.pwd  # app dir in dev or pwd otherwise
+dir = Rails.env.development? ? '.' : Dir.pwd # app dir in dev or pwd otherwise
 unless File.writable?(dir)
   warn "ERROR: directory #{dir.inspect} is not writable (the pagy-rails-app needs to create DB files)"
   exit 1
 end
 
-# Pagy initializer
-Pagy::DEFAULT[:limit]             = 10
-Pagy::DEFAULT[:limit_requestable] = true
-Pagy::Offset::DEFAULT[:overflow]  = :empty_page
-
 # Activerecord initializer
 ActiveRecord::Base.logger = Logger.new(OUTPUT)
 ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: "#{dir}/tmp/pagy-rails.sqlite3")
@@ -80,11 +75,15 @@ end
 # Models
 class Post < ActiveRecord::Base # :nodoc:
   has_many :comments
-end # :nodoc:
+end
+
+# :nodoc:
 
 class Comment < ActiveRecord::Base # :nodoc:
   belongs_to :post
-end # :nodoc:
+end
+
+# :nodoc:
 
 # Unused model, useful to test overriding conflicts
 module Calendar
@@ -107,10 +106,13 @@ end
 class CommentsController < ActionController::Base # :nodoc:
   include Rails.application.routes.url_helpers
   include Pagy::Backend
+  PAGY_DEFAULT = { limit:         10,
+                   maxable_limit: 100,
+                   overflow:      :empty_page }.freeze
 
   def index
-    @pagy, @comments = pagy_offset(Comment.all)
-    pagy_headers_merge(@pagy)
+    @pagy, @comments = pagy_offset(Comment.all, **PAGY_DEFAULT)
+    # pagy_headers_merge(@pagy)
     render inline: TEMPLATE
   end
 end

gem/apps/repro.ru

@@ -29,18 +29,15 @@ gemfile(ENV['PAGY_INSTALL_BUNDLE'] == 'true') do
   gem 'sinatra'
 end
 
-# Edit this section adding/removing the extras and Pagy::DEFAULT as needed
+# Edit this section adding the extras as needed
 # pagy initializer
-# Pagy::Offset::DEFAULT[:overflow]  = :empty_page
-# Pagy::DEFAULT[:limit_requestable] = true
 
 # Sinatra setup
 require 'sinatra/base'
 # Sinatra application
 class PagyRepro < Sinatra::Base
-  PAGY_DEFAULT = { overflow: :empty_page, limit_requestable: true }.freeze
-
   include Pagy::Backend
+  PAGY_DEFAULT = { maxable_limit: 100, overflow: :empty_page }.freeze
 
   get('/javascripts/:file') do
     format = params[:file].split('.').last