updated documentation

README.md

@@ -1,33 +1,22 @@
 # Pagy
 
 [![Gem Version](https://img.shields.io/gem/v/pagy.svg?label=pagy&colorA=99004d&colorB=cc0066)](https://rubygems.org/gems/pagy)
-![ruby](https://img.shields.io/badge/ruby-1.9+-ruby.svg?colorA=99004d&colorB=cc0066)
-![jruby](https://img.shields.io/badge/jruby-1.7+-jruby.svg?colorA=99004d&colorB=cc0066)
+![ruby](https://img.shields.io/badge/ruby-3.0+-ruby.svg?colorA=99004d&colorB=cc0066)
 [![CodeCov](https://img.shields.io/codecov/c/github/ddnexus/pagy.svg?colorA=1f7a1f&colorB=2aa22a)](https://codecov.io/gh/ddnexus/pagy)
 [![Build Status](https://img.shields.io/travis/ddnexus/pagy/master.svg?colorA=1f7a1f&colorB=2aa22a)](https://travis-ci.org/ddnexus/pagy/branches)
+![Rubocop Status](https://img.shields.io/badge/rubocop-passing-rubocop.svg?colorA=1f7a1f&colorB=2aa22a)
 [![MIT license](https://img.shields.io/badge/license-MIT-mit.svg?colorA=1f7a1f&colorB=2aa22a)](http://opensource.org/licenses/MIT)
+ [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4329/badge)](https://bestpractices.coreinfrastructure.org/projects/4329)
 ![Commits](https://img.shields.io/github/commit-activity/y/ddnexus/pagy.svg?label=commits&colorA=004d99&colorB=0073e6)
 ![Downloads](https://img.shields.io/gem/dt/pagy.svg?colorA=004d99&colorB=0073e6)
 [![Chat](http://img.shields.io/badge/gitter-ruby--pagy-purple.svg?colorA=800080&colorB=b300b3)](https://gitter.im/ruby-pagy/Lobby)
- [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/4329/badge)](https://bestpractices.coreinfrastructure.org/projects/4329)
 
 Pagy is the ultimate pagination gem that outperforms the others in each and every benchmark and comparison.
 
-## New in 3.0+
-
-- Pagy 3.0+ is considerably faster, lighter and more efficient than 2.0+ on modern environments (see the charts below)
-- The javascript nav helpers have been refactored for improved performance and more intuitive API
-- The i18n has been refactored, the dictionary files are simpler and 100% compliant with the i18n gem
-- Added a few new [extras](https://ddnexus.github.io/pagy/extras)
-- Added [Maximizing Performance](https://ddnexus.github.io/pagy/how-to#maximizing-performance) docs as a practical guide to choose the best options for your requirements and environment
-
-**Notice**: Updating from 2.0+ to 3.0+ requires just some search and replace and a little reorganization of your custom i18n dictionaries. Check the [CHANGELOG](https://github.com/ddnexus/pagy/blob/master/CHANGELOG.md) for details.
-
-**Suggestions**:
+## New in 4.0+
 
-- If you are using any `pagy*_nav` helper, [consider to switch](https://ddnexus.github.io/pagy/how-to#consider-the-nav_js) to `pagy*_nav_js`, which gives you the same output with a substancial performance boost.
-- If you are using any javascript frontend, take a look at the [metadata](https://ddnexus.github.io/pagy/extras/metadata) extra
-- For API pagination take a look at the [headers](http://ddnexus.github.io/pagy/extras/headers) extra
+- Dropped compatibility with legacy systems: use pagy 4.0+ only with ruby 3.0+. Use pagy 3.0+ for ruby/jruby systems (from ruby 1.9 to 2.7)
+- Updating to 4.0+ does not require any change in your code: it requires only ruby 3.0+
 
 ## Comparison with other gems
 
@@ -79,7 +68,6 @@ _The [IPS/Kb ratio](http://ddnexus.github.io/pagination-comparison/gems.html#eff
 - It works with fast helpers OR easy to edit templates _(see [more...](https://ddnexus.github.io/pagy/how-to#using-templates))_
 - It raises real `Pagy::OverflowError` exceptions that you can rescue from _(see [how...](https://ddnexus.github.io/pagy/how-to#handling-pagyoutofrangeerror-exception))_ or use the [overflow extra](http://ddnexus.github.io/pagy/extras/overflow) for a few ready to use common behaviors
 - It does not impose any difficult-to-override logic or output _(see [why...](https://ddnexus.github.io/pagy/index#really-easy-to-customize))_
-- It also works on legacy systems starting from ruby 1.9+ and jruby 1.7+
 
 ### Easy to use
 
@@ -182,7 +170,6 @@ Besides the classic pagination offered by the `pagy_nav` helpers, you can use a
 - [Quick Start](https://ddnexus.github.io/pagy/how-to#quick-start)
 - [Documentation](https://ddnexus.github.io/pagy/index)
 - [Changelog](https://github.com/ddnexus/pagy/blob/master/CHANGELOG.md)
-- [Legacy Changelog](https://github.com/ddnexus/pagy/blob/master/LEGACY_CHANGELOG.md)
 
 ### Support and Feedback
 
@@ -198,6 +185,8 @@ Pagy follows the [Semantic Versioning 2.0.0](https://semver.org/). Please, check
 
 Pull Requests are welcome!
 
+Setting up a development environment for Pagy is very simple if you use the [docker environment](https://github.com/ddnexus/pagy/tree/master/docker).
+
 Before spending time creating a (potentially complex) Pull Request, you can [Confirm on Gitter](https://gitter.im/ruby-pagy/Lobby) whether your proposed changes are going to be useful for most users.
 
 If you Create A Pull Request, please ensure that the "All checks have passed" indicator gets green light on the Pull Request page. That means that the tests passed and Codecov and Rubocop are happy.
@@ -220,14 +209,6 @@ Many thanks to:
 - [The Contributors](https://github.com/ddnexus/pagy/graphs/contributors) for all the smart code and suggestions merged in the project
 - [The Stargazers](https://github.com/ddnexus/pagy/stargazers) for showing their support
 
-## Caveats
-
-### Jruby 9.2+ random exceptions in tests
-
-One of the latest jruby version (9.2.+) raises a couple of random `Java::JavaLang::NullPointerException` while running the frontend tests in Travis. That doesn't happen with previous versions.
-
-It might be just another jruby bug or a number of possible things related to the tests or the Travis build that might or might not affect real usage. I am done with debugging jruby weirdness, so I am not going to investigate it further. If you get any info about it, please, create an issue.
-
 ## License
 
 This project is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

docs/api/javascript.md

@@ -24,7 +24,7 @@ Load the [pagy.js](https://github.com/ddnexus/pagy/blob/master/lib/javascripts/p
 
 ### Add the oj gem
 
-Although it's not a requirement, if you are on ruby 2.0+ (not jruby), and if you use any `*_nav_js` helper, you should add the `gem 'oj'` to your Gemfile. When available, Pagy will automatically use it to boost the performance. (Notice: It does nothing for normal, non-js helpers.)
+Although it's not a requirement, if you use any `*_nav_js` helper, you should consider adding the `gem 'oj'` to your Gemfile. When available, Pagy will automatically use it to boost the performance. (Notice: It does nothing for normal, non-js helpers.)
 
 ### In rails apps
 
@@ -292,4 +292,4 @@ $('#container').html("<%= j(render 'nav_js')%>");
 Pagy.init(document.getElementById('container'));
 ```
 
-**IMPORTANT**: The `document.getElementById('container')` argument will re-init the pagy elements just AJAX-rendered in the container div. If you miss it it will not work with AJAX.
+**IMPORTANT**: The `document.getElementById('container')` argument will re-init the pagy elements just AJAX-rendered in the container div. If you miss it, it will not work.

docs/how-to.md

@@ -111,7 +111,9 @@ You can copy the comprehensive and annotated [pagy.rb](https://github.com/ddnexu
 
 ## Environment Assumptions
 
-- ruby 1.9+ or jruby 1.7+
+- Pagy 4.0+ runs on ruby 3.0+
+
+Notice: Older versions run on ruby 1.9+ or jruby 1.7+ till ruby <3.0
 
 ### Out of the box assumptions
 
@@ -585,12 +587,11 @@ Here are some tips that will help chosing the best way to use Pagy, depending on
 
 If you need the classic pagination bar with links and info, then you have a couple of choices, depending on your environment:
 
-- If you are on ruby 2.0+, add the `oj` gem to your gemfile and use any `pagy*_nav_js` helper _(see [Javascript](api/javascript.md))_. That uses client side rendering and it is faster and lighter than using any `pagy*_nav` helper _(40x faster, 36x lighter and 1,410x more efficient than Kaminari)_. _Notice: the `oj` gem is not a requirement but helps the performance when it is available._
-- If you are on jruby (any version) or ruby 1.9.x, or you cannot install `oj` then use the `pagy*_nav` helper, which will give you the same performance of pagy v2.0 (33x faster; 26x lighter; 850x more efficient than Kaminari)
+- Add the `oj` gem to your gemfile and use any `pagy*_nav_js` helper _(see [Javascript](api/javascript.md))_. That uses client side rendering and it is faster and lighter than using any `pagy*_nav` helper _(40x faster, 36x lighter and 1,410x more efficient than Kaminari)_. _Notice: the `oj` gem is not a requirement but helps the performance when it is available._
 
 ### Consider the combo navs
 
-If you don't have strict requirements but still need to give the user total feedback and control on the page to display, then consider the `pagy*_combo_nav_js` helpers (faster and lighter when the `oj` gem is available). That gives you the best performance with nav info and UI _(48x faster, 48x lighter and 2,270x more efficient than Kaminari)_ also saving real estate.
+If you don't have strict requirements but still need to give the user total feedback and control on the page to display, then consider the `pagy*_combo_nav_js` helpers. They are faster and lighter, and even more when the `oj` gem is available. That gives you the best performance with nav info and UI _(48x faster, 48x lighter and 2,270x more efficient than Kaminari)_ also saving real estate.
 
 #### Consider the countless extra