From e08b0088a5b003c6c822343454bf440cbbd15a58 Mon Sep 17 00:00:00 2001
From: Domizio Demichelis <dd.nexus@gmail.com>
Date: Tue, 26 Nov 2024 15:23:04 +0700
Subject: [PATCH] Add release and constraint info to changelog and tests

---
 CHANGELOG.md              | 19 +++++++++++++++++++
 scripts/bump.rb           |  2 ++
 test/pagy/version_test.rb |  5 ++++-
 3 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df735b35e..30aebf62b 100644
--- a/CHANGELOG.md
+++ b/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:
diff --git a/scripts/bump.rb b/scripts/bump.rb
index ecdc0547c..f9541a16d 100755
--- a/scripts/bump.rb
+++ b/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
diff --git a/test/pagy/version_test.rb b/test/pagy/version_test.rb
index 6235e0384..74d521afa 100644
--- a/test/pagy/version_test.rb
+++ b/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+$/, '')}"