Restore 1.x API compatibility while keeping 1.5 hardening

ARCHITECTURE.md

@@ -38,3 +38,20 @@ with additional error codes based on the client's checks. When adding a new
 [`RequestMethod`](./src/ReCaptcha/RequestMethod.php) ensure that it returns the
 `ReCaptcha::E_CONNECTION_FAILED` and `ReCaptcha::E_BAD_RESPONSE` where
 appropriate.
+
+## Public API compatibility
+
+The 1.x line treats the following classes and interfaces as public API:
+`ReCaptcha`, `RequestMethod`, `Response`, `RequestParameters`,
+`RequestMethod\Post`, `RequestMethod\CurlPost`, and
+`RequestMethod\SocketPost`, plus the request wrapper classes
+`RequestMethod\Curl` and `RequestMethod\Socket`.
+
+Changes that narrow those APIs, such as adding native scalar parameter types,
+adding native return types to existing public methods, making public non-final
+classes `readonly` or `final`, removing public classes, or removing existing
+constructor argument forms, should be reserved for a major release.
+
+The `RequestMethod::submit()` interface intentionally keeps its 1.x-compatible
+native signature. Implementations are still expected to return the body of the
+reCAPTCHA response as a string.

README.md

@@ -15,7 +15,7 @@ and v3.
 - reCAPTCHA: https://cloud.google.com/security/products/recaptcha
 - This repo: https://github.com/google/recaptcha
 - Hosted demo: https://recaptcha-demo.appspot.com/
-- Version: 1.5.0
+- Version: 1.5.1
 - License: BSD, see [LICENSE](LICENSE)
 
 > [!IMPORTANT]
@@ -169,6 +169,11 @@ $recaptcha = new \ReCaptcha\ReCaptcha($secret, new \ReCaptcha\RequestMethod\Sock
 
 For more details on usage and structure, see [ARCHITECTURE](ARCHITECTURE.md).
 
+The 1.x line preserves compatibility for the public request and response APIs.
+See [Public API compatibility](ARCHITECTURE.md#public-api-compatibility) for
+details on which API changes require a major release.
+
+
 ### Examples
 
 You can see examples of each reCAPTCHA type in [examples/](examples/). You can

composer.json

@@ -25,14 +25,14 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-main": "1.4.x-dev"
+            "dev-main": "1.5.x-dev"
         }
     },
     "scripts": {
         "lint": "vendor/bin/php-cs-fixer -vvv check --using-cache=no",
         "lint-fix": "vendor/bin/php-cs-fixer -vvv fix --using-cache=no",
         "phpstan": "vendor/bin/phpstan",
-        "test": "XDEBUG_MODE=coverage vendor/bin/phpunit",
+        "test": "@php -d xdebug.mode=coverage vendor/bin/phpunit",
         "serve-examples": "@php -S localhost:8080 -t examples"
     },
     "config": {