Add requirement for doc snippets

Author: k0ka

AGENTS.md

@@ -103,6 +103,8 @@ Prefer adding focused tests around the exact operation being changed instead of
 - a corresponding sample test under `tests/sample/`
 - documentation in `doc/services/` if the feature is part of the supported public workflow
 
+All code snippets used in the docs must live in `samples/` rather than being maintained only inline in `.rst` files, and they must be covered by the sample test suite.
+
 Sample tests typically create a temporary PHP file from a template and `require_once` it, so keep samples self-contained and readable.
 
 ## Documentation
@@ -123,3 +125,4 @@ make -C doc html
 - Keep docblocks accurate for public APIs and option arrays.
 - Reuse existing fixtures, sample patterns, and helper methods before inventing new ones.
 - If `composer.json` changes, run `composer normalize` because CI auto-normalizes that file.
+

doc/services/compute/v2/server-groups.rst

@@ -39,19 +39,7 @@ Microversion 2.64+
 If the Compute service is created with microversion ``2.64`` or later, you can use the singular ``policy`` field and
 optional ``rules`` object instead:
 
-.. code-block:: php
-
-    $compute = $openstack->computeV2([
-        'microVersion' => '2.64',
-    ]);
-
-    $serverGroup = $compute->createServerGroup([
-        'name'   => 'db-group',
-        'policy' => 'anti-affinity',
-        'rules'  => [
-            'max_server_per_host' => 1,
-        ],
-    ]);
+.. sample:: Compute/v2/server_groups/create_2_64.php
 
 When Nova responds with the newer singular ``policy`` field, the SDK also exposes that value as the first item in
 ``policies`` for compatibility with the older response shape.

samples/Compute/v2/server_groups/create.php

@@ -12,10 +12,9 @@
     'scope'   => ['project' => ['id' => '{projectId}']],
 ]);
 
-$compute = $openstack->computeV2(['region' => '{region}', 'microVersion' => '2.64']);
+$compute = $openstack->computeV2(['region' => '{region}']);
 
 $serverGroup = $compute->createServerGroup([
-    'name'   => '{serverGroupName}',
-    'policy' => 'anti-affinity',
-    'rules'  => ['max_server_per_host' => 3],
+    'name'     => '{serverGroupName}',
+    'policies' => ['affinity'],
 ]);

samples/Compute/v2/server_groups/create_2_64.php

@@ -0,0 +1,26 @@
+<?php
+
+require 'vendor/autoload.php';
+
+$openstack = new OpenStack\OpenStack([
+    'authUrl' => '{authUrl}',
+    'region'  => '{region}',
+    'user'    => [
+        'id'       => '{userId}',
+        'password' => '{password}',
+    ],
+    'scope'   => ['project' => ['id' => '{projectId}']],
+]);
+
+$compute = $openstack->computeV2([
+    'region'       => '{region}',
+    'microVersion' => '2.64',
+]);
+
+$serverGroup = $compute->createServerGroup([
+    'name'   => '{serverGroupName}',
+    'policy' => 'anti-affinity',
+    'rules'  => [
+        'max_server_per_host' => 1,
+    ],
+]);

tests/sample/Compute/v2/ServerGroupTest.php

@@ -13,6 +13,26 @@ private function assertPolicy(ServerGroup $serverGroup, string $expected): void
         $this->assertEquals($expected, $serverGroup->policy);
     }
 
+    public function testCreateWithMicroversion264()
+    {
+        $name = $this->randomStr();
+
+        /** @var ServerGroup $serverGroup */
+        require_once $this->sampleFile('server_groups/create_2_64.php', ['{serverGroupName}' => $name]);
+
+        try {
+            $this->assertInstanceOf(ServerGroup::class, $serverGroup);
+            $this->assertEquals($name, $serverGroup->name);
+            $this->assertPolicy($serverGroup, 'anti-affinity');
+            $this->assertEquals(1, $serverGroup->rules['max_server_per_host']);
+        } finally {
+            $serverGroup->delete();
+        }
+
+        $this->expectException(BadResponseError::class);
+        $serverGroup->retrieve();
+    }
+
     public function testCreate(): ServerGroup
     {
         $name = $this->randomStr();
@@ -22,7 +42,7 @@ public function testCreate(): ServerGroup
 
         $this->assertInstanceOf(ServerGroup::class, $serverGroup);
         $this->assertEquals($name, $serverGroup->name);
-        $this->assertPolicy($serverGroup, 'anti-affinity');
+        $this->assertPolicy($serverGroup, 'affinity');
 
         return $serverGroup;
     }
@@ -60,7 +80,7 @@ public function testRead(ServerGroup $createdServerGroup)
         $this->assertInstanceOf(ServerGroup::class, $serverGroup);
         $this->assertEquals($createdServerGroup->id, $serverGroup->id);
         $this->assertEquals($createdServerGroup->name, $serverGroup->name);
-        $this->assertPolicy($serverGroup, 'anti-affinity');
+        $this->assertPolicy($serverGroup, 'affinity');
     }
 
     /**