Merge up 3.3.x into 4.0.x

.agents/skills/merge-up/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: merge-up
+description: >
+  Cascade-merge maintained branches from oldest to newest (e.g.
+  3.1.x → 3.2.x → 3.3.x → 4.0.x). Use when the user says "merge branches",
+  "merge up", "cascade merge", "sync branches", or "update branches".
+---
+
+# Branch Cascade Merge
+
+Merges each maintained branch into the next one, from oldest to newest.
+
+## Progress checklist
+
+- [ ] Step 0: Pre-flight checks
+- [ ] Step 1: Determine maintained branches and pull them
+- [ ] Step 2: Cascade merge loop
+
+---
+
+## Confirmation rule
+
+Whenever the skill says **"Wait for confirmation"**, treat anything other than an
+explicit affirmative as **no**: stop and ask the user how they want to proceed.
+
+---
+
+## Step 0 — Pre-flight checks
+
+```bash
+git status --porcelain --untracked-files=no
+```
+
+If any output, **stop**:
+> "The working tree is not clean. Please commit or stash your changes first."
+
+---
+
+## Step 1 — Determine maintained branches and pull them
+
+### 1a. Get the branch list
+
+Ask the user which branches to cascade-merge. The user should provide an
+ordered list from oldest to newest (e.g. `3.1.x 3.2.x 3.3.x 4.0.x`).
+
+If the user doesn't provide a list, determine it from remote branches:
+
+```bash
+git branch -r --list 'origin/*.*.x' | sed 's|origin/||' | sort -V
+```
+
+Present the list and **wait for confirmation** before proceeding. The user may
+want to exclude some branches (e.g. EOL branches). Store the confirmed list as
+`BRANCHES`.
+
+### 1b. Pull every branch
+
+For each branch in `BRANCHES`:
+
+```bash
+git checkout <branch>
+git pull --ff-only origin <branch>
+```
+
+Using `--ff-only` ensures local branches haven't diverged from origin. If the
+pull fails, **stop** and report the error.
+
+---
+
+## Step 2 — Cascade merge loop
+
+For each consecutive pair `(SOURCE, TARGET)` in `BRANCHES`:
+
+### 2a. Merge
+
+```bash
+git checkout <TARGET>
+git merge <SOURCE>
+```
+
+Three outcomes are possible:
+
+- **Already up-to-date:** print "✓ `<TARGET>` already up-to-date with `<SOURCE>`"
+  and skip to the next pair.
+- **Clean merge (no conflicts):** git creates the merge commit automatically.
+  Proceed directly to step 2c.
+- **Conflicts:** proceed to step 2b.
+
+### 2b. Resolve conflicts (only when git reports conflicts)
+
+List conflicts:
+
+```bash
+git diff --name-only --diff-filter=U
+```
+
+Read each conflicted file, resolve it, then `git add` it. When all are resolved:
+
+```bash
+git commit --no-edit
+```
+
+#### Conflict resolution rules
+
+| File pattern | Strategy |
+|---|---|
+| `CHANGELOG*.md` | Keep entries from both sides; newer branch entries on top |
+| Version constants, `composer.json` branch aliases | Keep the TARGET branch value |
+| `composer.json` dependency versions | Keep the TARGET branch value (newer branch may require higher versions) |
+| Code files | Merge logically based on context; when unsure, ask the user |
+
+After resolving, show `git diff HEAD~1` (first parent of the merge commit, i.e.
+the previous TARGET state) and wait for the user to confirm the resolution looks
+correct before proceeding.
+
+### 2c. Run tests
+
+Run the test suite to verify the merge didn't break anything:
+
+```bash
+composer install
+vendor/bin/phpunit
+```
+
+If the project uses `castor`, prefer:
+
+```bash
+composer install
+castor phpunit
+```
+
+If tests fail, first check whether the failure is pre-existing: run the same
+test on the TARGET branch before the merge. Only fix failures introduced by the
+merge:
+1. Analyze and fix the code.
+2. Commit the fix with a descriptive message.
+3. Re-run failing tests until green.
+
+Report any pre-existing failures to the user without attempting to fix them.
+
+### 2d. Ask for confirmation before pushing
+
+Show:
+
+```
+Merge: <SOURCE> → <TARGET>
+Tests: all passing
+
+Commits since origin/<TARGET>:
+git log --oneline origin/<TARGET>..<TARGET>
+
+Ready to push? (yes / no)
+```
+
+**Wait for confirmation.** The user may make changes themselves before confirming.
+
+### 2e. Push and continue
+
+```bash
+git push origin <TARGET>
+```
+
+If the push fails, **stop** and report the error.
+
+Print "✓ `<SOURCE>` → `<TARGET>` done." and continue to the next pair.
+
+---
+
+## Final summary
+
+```
+All merges complete:
+  3.1.x → 3.2.x  ✓
+  3.2.x → 3.3.x  ✓
+  3.3.x → 4.0.x  ✓
+```
+
+---
+
+## Gotchas
+
+- `CHANGELOG.md` conflicts are the most common; entries must be kept from both
+  sides, never dropped.
+- A merge can introduce test failures even without conflicts, because behavior
+  from the older branch may be incompatible with newer code. Always run tests.
+- When merging across major versions (e.g. 3.x → 4.x), pay extra attention to
+  breaking changes, removed deprecations, and updated PHP version requirements.
+
+## Error handling
+
+- **Never** force-push or rewrite history.
+- **Never** use `--no-verify` on commits.
+- **Never** auto-recover from a failed `git push` or `git pull`. Stop and hand
+  control back to the user.

.ci-tools/phpstan-baseline.neon

@@ -282,12 +282,6 @@ parameters:
 			count: 3
 			path: ../src/OtherObject/DoublePrecisionFloatObject.php
 
-		-
-			rawMessage: 'Parameter #2 $data of class CBOR\OtherObject\DoublePrecisionFloatObject constructor expects string|null, string|false given.'
-			identifier: argument.type
-			count: 1
-			path: ../src/OtherObject/DoublePrecisionFloatObject.php
-
 		-
 			rawMessage: Class "CBOR\OtherObject\FalseObject" is not allowed to extend "CBOR\OtherObject".
 			identifier: ergebnis.noExtends
@@ -312,6 +306,24 @@ parameters:
 			count: 1
 			path: ../src/OtherObject/GenericObject.php
 
+		-
+			rawMessage: Binary operation "&" between mixed and 8388607 results in an error.
+			identifier: binaryOp.invalid
+			count: 1
+			path: ../src/OtherObject/HalfPrecisionFloatObject.php
+
+		-
+			rawMessage: Binary operation ">>" between mixed and 23 results in an error.
+			identifier: binaryOp.invalid
+			count: 1
+			path: ../src/OtherObject/HalfPrecisionFloatObject.php
+
+		-
+			rawMessage: Cannot access offset 1 on array|false.
+			identifier: offsetAccess.nonOffsetAccessible
+			count: 2
+			path: ../src/OtherObject/HalfPrecisionFloatObject.php
+
 		-
 			rawMessage: Class "CBOR\OtherObject\HalfPrecisionFloatObject" is not allowed to extend "CBOR\OtherObject".
 			identifier: ergebnis.noExtends
@@ -414,12 +426,6 @@ parameters:
 			count: 3
 			path: ../src/OtherObject/SinglePrecisionFloatObject.php
 
-		-
-			rawMessage: 'Parameter #2 $data of class CBOR\OtherObject\SinglePrecisionFloatObject constructor expects string|null, string|false given.'
-			identifier: argument.type
-			count: 1
-			path: ../src/OtherObject/SinglePrecisionFloatObject.php
-
 		-
 			rawMessage: Class "CBOR\OtherObject\TrueObject" is not allowed to extend "CBOR\OtherObject".
 			identifier: ergebnis.noExtends
@@ -564,6 +570,24 @@ parameters:
 			count: 1
 			path: ../src/Tag/Base64UrlTag.php
 
+		-
+			rawMessage: Binary operation "&" between mixed and 4503599627370495 results in an error.
+			identifier: binaryOp.invalid
+			count: 1
+			path: ../src/Tag/BigFloatTag.php
+
+		-
+			rawMessage: Binary operation ">>" between mixed and 52 results in an error.
+			identifier: binaryOp.invalid
+			count: 1
+			path: ../src/Tag/BigFloatTag.php
+
+		-
+			rawMessage: Cannot access offset 1 on array|false.
+			identifier: offsetAccess.nonOffsetAccessible
+			count: 2
+			path: ../src/Tag/BigFloatTag.php
+
 		-
 			rawMessage: Class "CBOR\Tag\BigFloatTag" is not allowed to extend "CBOR\Tag".
 			identifier: ergebnis.noExtends
@@ -708,6 +732,18 @@ parameters:
 			count: 1
 			path: ../src/Tag/NegativeBigIntegerTag.php
 
+		-
+			rawMessage: Class "CBOR\Tag\SelfDescribeCBORTag" is not allowed to extend "CBOR\Tag".
+			identifier: ergebnis.noExtends
+			count: 1
+			path: ../src/Tag/SelfDescribeCBORTag.php
+
+		-
+			rawMessage: 'Method CBOR\Tag\SelfDescribeCBORTag::createFromLoadedData() has parameter $data with a nullable type declaration.'
+			identifier: ergebnis.noParameterWithNullableTypeDeclaration
+			count: 1
+			path: ../src/Tag/SelfDescribeCBORTag.php
+
 		-
 			rawMessage: 'Method CBOR\Tag\TagInterface::createFromLoadedData() has parameter $data with a nullable type declaration.'
 			identifier: ergebnis.noParameterWithNullableTypeDeclaration

.ci-tools/rector.php

@@ -16,15 +16,15 @@
 }
 $builder->withSets([
     SetList::DEAD_CODE,
-    LevelSetList::UP_TO_PHP_81,
+    LevelSetList::UP_TO_PHP_80,
     DoctrineSetList::DOCTRINE_CODE_QUALITY,
     DoctrineSetList::ANNOTATIONS_TO_ATTRIBUTES,
     PHPUnitSetList::PHPUNIT_CODE_QUALITY,
     PHPUnitSetList::ANNOTATIONS_TO_ATTRIBUTES,
     PHPUnitSetList::PHPUNIT_120,
 ]);
 $builder->withComposerBased(twig: true, doctrine: true, phpunit: true, symfony: true);
-$builder->withPhpVersion(PhpVersion::PHP_81);
+$builder->withPhpVersion(PhpVersion::PHP_80);
 $builder->withPaths(
     [
         __DIR__ . '/../src',

.gitattributes

@@ -3,9 +3,11 @@
 /.ci-tools export-ignore
 /.github export-ignore
 /bin export-ignore
+/doc export-ignore
 /tests export-ignore
 /.editorconfig export-ignore
 /.gitattributes export-ignore
 /.gitignore export-ignore
 /.gitsplit.yml export-ignore
 /castor.php export-ignore
+/.agents export-ignore