From 7691034fcbd0b7aad5ce518ec27d6d2389fcdcc4 Mon Sep 17 00:00:00 2001
From: Kazuki Yamaguchi <k@rhe.jp>
Date: Thu, 31 Aug 2023 18:46:41 +0900
Subject: [PATCH] Update README and gemspec description

 * Reword the description in README for more clarity.

 * Add a compatibility matrix of our stable branches and explain the
   maintenance policy.

 * Remove the obsolete paragraph for how to use the gem in Ruby 2.3,
   which is no longer supported.
---
 README.md       | 55 ++++++++++++++++++++++++++++++++-----------------
 openssl.gemspec |  4 ++--
 2 files changed, 38 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index a23135ee4..b57758b2a 100644
--- a/README.md
+++ b/README.md
@@ -2,26 +2,53 @@
 
 [![Actions Status](https://github.com/ruby/openssl/workflows/CI/badge.svg)](https://github.com/ruby/openssl/actions?workflow=CI)
 
+**OpenSSL for Ruby** provides access to SSL/TLS and general-purpose
+cryptography based on the OpenSSL library.
 
-OpenSSL provides SSL, TLS and general purpose cryptography. It wraps the
-OpenSSL library.
+OpenSSL for Ruby is sometimes referred to as **openssl** in all lowercase
+or **Ruby/OpenSSL** for disambiguation.
+
+## Compatibility and maintenance policy
+
+OpenSSL for Ruby is released as a RubyGems gem. At the same time, it is part of
+the standard library of Ruby. This is called a [default gem].
+
+Each stable branch of OpenSSL for Ruby will remain supported as long as it is
+included as a default gem in [supported Ruby branches][Ruby Maintenance Branches].
+
+|Version|Maintenance status             |Ruby compatibility|OpenSSL compatibility                       |
+|-------|-------------------------------|------------------|--------------------------------------------|
+|3.2.x  |normal maintenance (Ruby 3.3)  |Ruby 2.7+         |OpenSSL 1.0.2-3.1 (current) or LibreSSL 3.1+|
+|3.1.x  |normal maintenance (Ruby 3.2)  |Ruby 2.6+         |OpenSSL 1.0.2-3.1 (current) or LibreSSL 3.1+|
+|3.0.x  |normal maintenance (Ruby 3.1)  |Ruby 2.6+         |OpenSSL 1.0.2-3.1 (current) or LibreSSL 3.1+|
+|2.2.x  |security maintenance (Ruby 3.0)|Ruby 2.3+         |OpenSSL 1.0.1-1.1.1 or LibreSSL 2.9+        |
+|2.1.x  |end-of-life (Ruby 2.5-2.7)     |Ruby 2.3+         |OpenSSL 1.0.1-1.1.1 or LibreSSL 2.5+        |
+|2.0.x  |end-of-life (Ruby 2.4)         |Ruby 2.3+         |OpenSSL 0.9.8-1.1.1 or LibreSSL 2.3+        |
+
+[default gem]: https://docs.ruby-lang.org/en/master/standard_library_rdoc.html
+[Ruby Maintenance Branches]: https://www.ruby-lang.org/en/downloads/branches/
 
 ## Installation
 
-The openssl gem is available at [rubygems.org](https://rubygems.org/gems/openssl).
-You can install with:
+> **Note**
+> The openssl gem is included with Ruby by default, but you may wish to upgrade
+> it to a newer version available at
+> [rubygems.org](https://rubygems.org/gems/openssl).
+
+To upgrade it, you can use RubyGems:
 
 ```
 gem install openssl
 ```
 
-You may need to specify the path where OpenSSL is installed.
+In some cases, it may be necessary to specify the path to the installation
+directory of the OpenSSL library.
 
 ```
 gem install openssl -- --with-openssl-dir=/opt/openssl
 ```
 
-Alternatively, you can install the gem with `bundler`:
+Alternatively, you can install the gem with Bundler:
 
 ```ruby
 # Gemfile
@@ -30,7 +57,7 @@ gem 'openssl'
 gem 'openssl', git: 'https://github.com/ruby/openssl'
 ```
 
-After doing `bundle install`, you should have the gem installed in your bundle.
+After running `bundle install`, you should have the gem installed in your bundle.
 
 ## Usage
 
@@ -40,15 +67,6 @@ Once installed, you can require "openssl" in your application.
 require "openssl"
 ```
 
-**NOTE**: If you are using Ruby 2.3 (and not Bundler), you **must** activate
-the gem version of openssl, otherwise the default gem packaged with the Ruby
-installation will be used:
-
-```ruby
-gem "openssl"
-require "openssl"
-```
-
 ## Documentation
 
 See https://ruby.github.io/openssl/.
@@ -57,10 +75,9 @@ See https://ruby.github.io/openssl/.
 
 Please read our [CONTRIBUTING.md] for instructions.
 
+[CONTRIBUTING.md]: https://github.com/ruby/openssl/tree/master/CONTRIBUTING.md
+
 ## Security
 
 Security issues should be reported to ruby-core by following the process
 described on ["Security at ruby-lang.org"](https://www.ruby-lang.org/en/security/).
-
-
-[CONTRIBUTING.md]: https://github.com/ruby/openssl/tree/master/CONTRIBUTING.md
diff --git a/openssl.gemspec b/openssl.gemspec
index 674dc20de..c194b5049 100644
--- a/openssl.gemspec
+++ b/openssl.gemspec
@@ -3,8 +3,8 @@ Gem::Specification.new do |spec|
   spec.version       = "3.1.0"
   spec.authors       = ["Martin Bosslet", "SHIBATA Hiroshi", "Zachary Scott", "Kazuki Yamaguchi"]
   spec.email         = ["ruby-core@ruby-lang.org"]
-  spec.summary       = %q{OpenSSL provides SSL, TLS and general purpose cryptography.}
-  spec.description   = %q{It wraps the OpenSSL library.}
+  spec.summary       = %q{SSL/TLS and general-purpose cryptography for Ruby}
+  spec.description   = %q{OpenSSL for Ruby provides access to SSL/TLS and general-purpose cryptography based on the OpenSSL library.}
   spec.homepage      = "https://github.com/ruby/openssl"
   spec.license       = "Ruby"