Add release and constraint info to changelog and tests

CHANGELOG.md

@@ -4,6 +4,25 @@ 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 functionality to be supported ONLY during the next releases belonging to the same MAYOR version.
+
+## Recommended Version Constraint
+
+Given a version number `MAJOR.MINOR.PATCH` (e.g. `9.3.1`):
+
+The `gem 'pagy', '~> 9.3'` 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 indicated in the Gemfile ONLY when you are ready to handle the BREAKING CHANGES
+
 ## Breaking Changes
 
 If you upgrade from version `< 9.0.0` see the following:

scripts/bump.rb

@@ -64,6 +64,8 @@
 
 # Update the CHANGELOG
 replace_string_in_file('CHANGELOG.md', /<hr>\n/, "<hr>\n\n## Version #{new_version}\n\n#{changes}")
+replace_string_in_file('CHANGELOG.md', "(e.g. `#{old_version}", "(e.g. `#{new_version}")
+replace_string_in_file('CHANGELOG.md', *["~> #{old_version}", "~> #{new_version}"].map { |v| v.split('.')[0, 2].join('.') })
 
 # Bump the version in files
 (%w[retype.yml

test/pagy/version_test.rb

@@ -34,7 +34,10 @@
     _(Pagy.root.join('javascripts', 'pagy.mjs').read).must_match "version: \"#{Pagy::VERSION}\","
   end
   it 'defines the same version in CHANGELOG.md' do
-    _(Pagy.root.parent.join('CHANGELOG.md').read).must_match "## Version #{Pagy::VERSION}"
+    changelog = Pagy.root.parent.join('CHANGELOG.md').read
+    _(changelog).must_match "(e.g. `#{Pagy::VERSION}"
+    _(changelog).must_match "gem 'pagy', '~> #{Pagy::VERSION.sub(/\.\d+$/, '')}"
+    _(changelog).must_match "## Version #{Pagy::VERSION}"
   end
   it 'defines the same minor version in ./quick-start.md' do
     _(File.read('./quick-start.md')).must_match "gem 'pagy', '~> #{Pagy::VERSION.sub(/\.\d+$/, '')}"