From c11df0ae63e6132c25324097bd11cf77ae2551de Mon Sep 17 00:00:00 2001 From: Paragon Initiative Enterprises Date: Fri, 19 Apr 2024 05:15:12 -0400 Subject: [PATCH] New major version policy --- README.md | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 60aa447f..36cc3c28 100644 --- a/README.md +++ b/README.md @@ -11,12 +11,47 @@ Sodium Compat is a pure PHP polyfill for the Sodium cryptography library (libsodium), a core extension in PHP 7.2.0+ and otherwise [available in PECL](https://pecl.php.net/package/libsodium). -This library tentatively supports PHP 5.2.4 - 8.x (latest), but officially -only supports [non-EOL'd versions of PHP](https://secure.php.net/supported-versions.php). - If you have the PHP extension installed, Sodium Compat will opportunistically and transparently use the PHP extension instead of our implementation. +## Major Versions and Branches + +sodium_compat v1.21.0 was the last v1.x release from the master branch. From now +on, all future releases that support PHP 5.2 - 5.6 and 32-bit integers will be +[in the `v1.x` branch](v1.x). + +Newer versions of sodium_compat (i.e., v2.0.0) will continue to live in the master +branch, unless a new major version is needed. The goal of this work is to improve +code readability and performance, while reducing boilerplate code. + +When in doubt, refer to the README file in [the master branch](https://github.com/paragonie/sodium_compat/blob/master/README.md) +for the latest in version information. + +### Which version should I use? + +| sodium_compat version | PHP versions supported | 32-bit support? | Branch | +|-----------------------|------------------------|-----------------|---------------------------------------------------------------| +| `v1.x.y` | 5.2.4 - LATEST | YES | [v1.x](https://github.com/paragonie/sodium_compat/tree/v1.x) | +| `v2.x.y` | 7.2 - LATEST | NO | **master** | + +If you need 32-bit PHP support (`PHP_INT_SIZE == 4`), continue using sodium_compat v1.x. +If you want improved performance and smaller dependencies, use v2.x. + +We recommend libraries and frameworks set a Composer version constraint as follows: + +```javascript +{ + "require": { + /* ... */ + "paragonie/sodium_compat": ">= 1" + /* ... */ + } +} +``` + +Applications should, conversely, specify the actual version that matters to them +and their deployments. + ## IMPORTANT! This cryptography library has not been formally audited by an independent third