From 4f7c0d8041338407afc8f58512d4561e7591425d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pech=20Jind=C5=99ich?= <jindrich.pech@almacareer.com>
Date: Mon, 6 Oct 2025 10:36:50 +0200
Subject: [PATCH] Release version 5.0.0

---
 CHANGELOG.md   |  5 ++-
 README.md      |  5 ++-
 UPGRADE-5.0.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 107 insertions(+), 2 deletions(-)
 create mode 100644 UPGRADE-5.0.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b8c76e1..a3d2c5e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,10 @@
 <!-- There is always Unreleased section on the top. Subsections (Added, Changed, Fixed, Removed) should be added as needed. -->
 
 ## Unreleased
-- Remove skip of BlankLineAfterOpeningTagFixer to be PSR-12 compliant.
+
+## 5.0.0 - TBD
+- **BC break:** Change namespace from `Lmc\CodingStandard` to `AlmaOss\CodingStandard`. See [UPGRADE-5.0.md](UPGRADE-5.0.md) for step-by-step upgrade howto.
+- **BC break:** Remove skip of `BlankLineAfterOpeningTagFixer` to be PSR-12 compliant. A blank line after the opening PHP tag is now required.
 
 ## 4.2.0 - 2025-02-28
 - Rename the package from "Alma Career Czechia Standard for PHP" to more broad "Alma Career Coding Standard for PHP". 🎉
diff --git a/README.md b/README.md
index a41eea2..f7d0c3c 100644
--- a/README.md
+++ b/README.md
@@ -12,12 +12,15 @@ We use [EasyCodingStandard][ecs] to define and execute checks created for both [
 ## Switching from lmc/coding-standard
 
 The package `almacareer/coding-standard` is 1:1 replacement for the previous deprecated `lmc/coding-standard` package.
+
+⚠️ **Note:** Starting from version 5.0.0, the namespace has changed from `Lmc\CodingStandard` to `AlmaOss\CodingStandard`. See [UPGRADE-5.0.md](UPGRADE-5.0.md) for detailed upgrade instructions.
+
 To change the package, you only need to do the following changes in your project:
 
 ### 1. Update dependency in composer.json
 ```diff
 -        "lmc/coding-standard": "^4.1",
-+        "almacareer/coding-standard": "^4.2",
++        "almacareer/coding-standard": "^5.0",
 ```
 
 And then run `composer update`.
diff --git a/UPGRADE-5.0.md b/UPGRADE-5.0.md
new file mode 100644
index 0000000..292c7c0
--- /dev/null
+++ b/UPGRADE-5.0.md
@@ -0,0 +1,99 @@
+# Upgrading from 4.x to 5.0
+
+### 1. Update dependency in composer.json
+In the `require-dev` section of `composer.json` change the version constraint:
+
+```diff
+-        "almacareer/coding-standard": "^4.2",
++        "almacareer/coding-standard": "^5.0",
+```
+
+Then run `composer update almacareer/coding-standard`.
+
+### 2. Update namespace imports
+
+**[BC break]** The namespace has been changed from `Lmc\CodingStandard` to `AlmaOss\CodingStandard`.
+
+Update your `ecs.php` file to use the new namespace:
+
+```diff
+<?php
+
+declare(strict_types=1);
+
+-use Lmc\CodingStandard\Set\SetList;
++use AlmaOss\CodingStandard\Set\SetList;
+ use Symplify\EasyCodingStandard\Config\ECSConfig;
+
+return ECSConfig::configure()
+    ->withSets(
+        [
+            SetList::ALMACAREER,
+        ]
+    );
+```
+
+If you are using any custom sniffs or fixers from this package in your configuration, update their namespace as well:
+
+```diff
+-use Lmc\CodingStandard\Fixer\SpecifyArgSeparatorFixer;
++use AlmaOss\CodingStandard\Fixer\SpecifyArgSeparatorFixer;
+
+-use Lmc\CodingStandard\Sniffs\Naming\ClassNameSuffixByParentSniff;
++use AlmaOss\CodingStandard\Sniffs\Naming\ClassNameSuffixByParentSniff;
+```
+
+### 3. PSR-12 compliance change
+
+**[BC break]** The `BlankLineAfterOpeningTagFixer` is no longer skipped. This means that a blank line after the opening PHP tag (`<?php`) is now required to be PSR-12 compliant.
+
+Before (no longer valid):
+```php
+<?php
+declare(strict_types=1);
+```
+
+After (PSR-12 compliant):
+```php
+<?php
+
+declare(strict_types=1);
+```
+
+If your codebase does not follow this convention yet, running `vendor/bin/ecs check --fix` will automatically add the blank lines.
+
+If you want to keep the old behavior and skip this check, you can add it to your `ecs.php`:
+
+```php
+use PhpCsFixer\Fixer\Whitespace\BlankLineAfterOpeningTagFixer;
+
+return ECSConfig::configure()
+    // ...
+    ->withSkip([
+        BlankLineAfterOpeningTagFixer::class,
+    ]);
+```
+
+### 4. Run the code style checks
+
+After updating the namespace, run the code style checks to ensure everything is working correctly:
+
+```bash
+vendor/bin/ecs check
+```
+
+To automatically fix the code style issues (including the blank line after opening tag):
+
+```bash
+vendor/bin/ecs check --fix
+```
+
+### 5. Sanity check
+
+You can ensure all predefined checks are loaded by running:
+
+```sh
+vendor/bin/ecs list-checkers
+```
+
+The output should show all the loaded checkers from both PHP-CS-Fixer and PHP_CodeSniffer.