WIP: Upgrade story

CHANGELOG.md

@@ -12,6 +12,47 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Removed
 
+# 4.28.0 (25 December 2023)
+## Added
+- **Configurable strategies**: You can now configure strategies individually, by using the _tuple_ format. A tuple is an array with two elements; the first is the strategy class, and the second is the settings array. For instance, you can configure response calls to only be used on certain endpoints:
+  ```php
+  'responses' => [
+      Strategies\Responses\UseResponseAttributes::class,
+      [
+        Strategies\Responses\ResponseCalls::class,
+        ['only' => ['GET *']],
+      ]
+  ],
+  ```
+- **Disable strategies per endpoint**: All strategies (including custom strategies) now support the `only` and `except` settings, allowing you to specify the routes you want them to be applied to, or the opposite.
+    ```php
+  'bodyParameters' => [
+      [
+        Strategies\BodyParameters\GetFromInlineValidator::class,
+        ['except' => ['POST /special-endpoint']],
+      ],
+      [
+        App\Docs\Strategies\SomeCoolStuff::class,
+        ['only' => ['POST /cool-endpoint']],
+      ],
+  ],
+  ```
+- **Easily override returned values**: The new `override` strategy (also a tuple) is a simple way to say "merge these values into the result of other strategies", without having to write a whole strategy. A common use case is for adding headers:
+  ```php
+  'headers' => [
+      Strategies\Responses\UseHeaderAttribute::class,
+      [
+        'override',
+        [
+          'Content-Type' => 'application/json'],
+          'Accept' => 'application/json'],
+      ]
+  ],
+  ```
+  
+- **New config format**: In an effort to simplify the config file and surface the most useful items, we're trying out a new config format which should be the default in v5. See [the docs]() for details.
+- **Better route matching**: Route matching now works with both method and URL. Previously, in you could only specify route name or URL. Now you can also specify "GET /path", "GET path", or "GET pa*".
+
 # 4.27.0 (21 December 2023)
 ## Modified
 - Allow Symfony v7

src/Config/Serializer.php

@@ -7,16 +7,6 @@ use Illuminate\Support\Str;
 
 class Serializer
 {
-    // todo new features & breaking changes:
-    // - strategy config tuples - responseCalls support
-    // - support route method + path in route matching
-    // - no more route groups, header apply rules move to override
-    // - no more apply rules for response_calls, use strategy settings. methods is replaced by only/except
-    // todo design beta/migration story
-    // todo design upgrade story
-    // todo design continuous upgrade story
-    // todo document parameters
-    // todo support multiple base URLs
     public static function toOldConfig(Extracting $extractingConfig, Output $outputConfig): array
     {
         return [
@@ -24,7 +14,7 @@ class Serializer
             'theme' => $outputConfig->theme,
             'title' => $outputConfig->title,
             'description' => $outputConfig->description,
-            'base_url' => $outputConfig->baseUrls[0] ?? null,
+            'base_url' => Arr::first($outputConfig->baseUrls) ?? null,
             'type' => $outputConfig->type[0],
             $outputConfig->type[0] => self::translateKeys($outputConfig->type[1]),
             'try_it_out' => self::translateKeys($outputConfig->tryItOut),

src/ScribeServiceProvider.php

@@ -92,7 +92,11 @@ class ScribeServiceProvider extends ServiceProvider
         ], 'scribe-config');
 
         $this->mergeConfigFrom(__DIR__ . '/../config/scribe.php', 'scribe');
-        // This is really only used in internal testing.
+        // This is really only used in internal testing,
+        // but we also make it publishable for easy migration, so there's no .
+        $this->publishes([
+            __DIR__ . '/../config/scribe.php' => $this->app->configPath('scribe.php'),
+        ], 'scribe-config');
         $this->mergeConfigFrom(__DIR__ . '/../config/scribe_new.php', 'scribe_new');
     }