From a33c22ca80caa5f547d63ecd8dcea5c12e7a9093 Mon Sep 17 00:00:00 2001 From: Domizio Demichelis Date: Sat, 18 Jan 2025 21:37:22 +0700 Subject: [PATCH] WIP: Add a few notes about the new changelog --- CHANGELOG-10.md | 164 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 164 insertions(+) create mode 100644 CHANGELOG-10.md diff --git a/CHANGELOG-10.md b/CHANGELOG-10.md new file mode 100644 index 000000000..cabe61dcd --- /dev/null +++ b/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 + +
+ +## 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/'` from the initializer. + +##### `elasticsearch_rails`, `meilisearch`, `searchkick` + +- Remove the `require 'pagy/extras/'` from the initializer +- Replace your existing (if any) `Pagy.new_from_` with `pagy_`. _(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) `:_pagy_search` + variable from your code, and use the original `pagy_search` method. +- Rename the existing (if any) `:_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)