Skip to content

Commit 2606b51

Browse files
Jurj-BogdanJurj-Bogdan
committed
upgrade from 5.2 to 5.3 steps
Signed-off-by: Jurj-Bogdan <[email protected]>
1 parent 230b666 commit 2606b51

File tree

2 files changed

+176
-15
lines changed

2 files changed

+176
-15
lines changed

‎docs/book/v5/upgrading.md‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,17 @@
1-
# Upgrades
2-
3-
Dotkernel API does not provide an automatic upgrade path.
4-
Instead, the recommended procedure is to manually implement each modification listed in [releases](https://github.com/dotkernel/api/releases).
5-
Additionally, release info can also be accessed as an [RSS](https://github.com/dotkernel/api/releases.atom) feed.
6-
7-
## Upgrade procedure
8-
9-
Once you clone Dotkernel API, you will find a [CHANGELOG.md](https://github.com/dotkernel/api/blob/5.0/CHANGELOG.md) file in the root of the project.
10-
This file contains a list of already implemented features in reverse chronological order.
11-
You can use this file to track the version of your copy of Dotkernel API.
12-
13-
For each new release you need implement the modifications from its pull requests in your project.
14-
It is recommended to copy the release info into your project's CHANGELOG.md file.
15-
This allows you to track your API's version and keep your project up-to-date with future releases.
1+
# Upgrades
2+
3+
Dotkernel API does not provide an automatic upgrade path.
4+
Instead, the recommended procedure is to manually implement each modification listed in [releases](https://github.com/dotkernel/api/releases).
5+
Additionally, release info can also be accessed as an [RSS](https://github.com/dotkernel/api/releases.atom) feed.
6+
7+
## Upgrade procedure
8+
9+
Once you clone Dotkernel API, you will find a [CHANGELOG.md](https://github.com/dotkernel/api/blob/5.0/CHANGELOG.md) file in the root of the project.
10+
This file contains a list of already implemented features in reverse chronological order.
11+
You can use this file to track the version of your copy of Dotkernel API.
12+
13+
For each new release you need implement the modifications from its pull requests in your project.
14+
It is recommended to copy the release info into your project's CHANGELOG.md file.
15+
This allows you to track your API's version and keep your project up-to-date with future releases.
16+
17+
Starting from [version 5.3](upgrading/UPGRADE-5.3.md) the upgrading procedure is detailed version to version.

‎docs/book/v5/upgrading/UPGRADE-5.3.md‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
# UPGRADE FROM 5.2 TO 5.3
2+
3+
-------------------------
4+
5+
Dotkernel API 5.3 is a minor release. As such, no significant backward compatibility breaks are expected,
6+
with minor backward compatibility breaks being prefixed in this document with `[BC BREAK]`.
7+
8+
This document only covers upgrading from version 5.2.
9+
10+
## Table of Contents
11+
12+
-------------------------
13+
14+
* [Update Phpstan memory limit](#update-phpstan-memory-limit)
15+
* [Update anonymization](#update-anonymization)
16+
* [Update User status and remove isDeleted properties](#update-user-status-and-remove-isdeleted-properties)
17+
* [Update dotkernel/dot-mail to version 5.0](#update-dotkerneldot-mail-to-version-50)
18+
* [Add post install script](#add-post-install-script)
19+
* [Remove post-create-project-cmd](#remove-post-create-project-cmd)
20+
* [Update security.txt](#update-securitytxt)
21+
* [Update coding standards](#update-coding-standards)
22+
* [Fix codecov.yml](#fix-codecovyml)
23+
* [Update Qodana configuration](#update-qodana-configuration)
24+
* [Remove laminas/laminas-http](#remove-laminaslaminas-http)
25+
26+
### Update Phpstan memory limit
27+
28+
* Add the `--memory-limit 1G` option to the `static-analysis` script found in `composer.json`
29+
> With the default `memory_limit=128M` on our WSL containers, PHPStan runs out of memory
30+
>
31+
> Note that you can set the memory limit to a value of your choosing, with a recommended minimum of 256M
32+
33+
### Update anonymization
34+
35+
* Add the `userAnonymizeAppend` key to the returned array in `config/autoload/local.php`, as well as to the distributed`config/autoload/local.php.dist`
36+
37+
```php
38+
'userAnonymizeAppend' => '',
39+
```
40+
41+
* Update the `anonymizeUser` function in `src/User/src/Service/UserService.php` to use the new key
42+
43+
Before:
44+
45+
```php
46+
$user->setIdentity($placeholder) //...
47+
```
48+
49+
After:
50+
51+
```php
52+
$user->setIdentity($placeholder . $this->config['userAnonymizeAppend']) //...
53+
```
54+
55+
> Note that any custom functionality using the old format will require updates
56+
57+
### Update User status and remove isDeleted properties
58+
59+
* [BC Break] Remove the `isDeleted` property from the `User` class, alongside all usages, as seen in the [pull request](https://github.com/dotkernel/api/pull/359/files)
60+
* Add a new "deleted" case to `UserStatusEnum`, which is to be used instead of the previous `isDeleted` property
61+
* Update the database and it's migrations to reflect the new structure
62+
> The use of "isDeleted" was redundant in the default application, and as such was removed
63+
>
64+
> All default methods are updated, but any custom functionality using "isDeleted" will require refactoring
65+
66+
### Update `dotkernel/dot-mail` to version 5.0
67+
68+
* Bump `dotkernel/dot-mail` to "^5.0" in `composer.json`
69+
* As the mail configuration file is now directly copied from the vendor via [script](#add-post-install-script), remove the existing `config/autoload/mail.global.php[.dist]` file(s)
70+
* Update the content for each of these configuration files to reflect the new structure from [dotkernel/dot-mail](https://github.com/dotkernel/dot-mail/blob/5.0/config/mail.global.php.dist)
71+
* Remove `Laminas\Mail\ConfigProvider::class` from `config/config.php`
72+
> The list of changes can be seen in the [pull request](https://github.com/dotkernel/api/pull/368/files)
73+
>
74+
> You can read more about the reasons for this change on the [Dotkernel blog](https://www.dotkernel.com/dotkernel/replacing-laminas-mail-with-symfony-mailer-in-dot-mail/).
75+
76+
### Remove `post-create-project-cmd`
77+
78+
* Remove the `post-create-project-cmd` key found under `scripts` in `composer.json`
79+
80+
```json
81+
"post-create-project-cmd": [
82+
"@development-enable"
83+
],
84+
```
85+
86+
### Add post install script
87+
88+
* Add `bin/composer-post-install-script.php` to automate the post installation copying of distributed configuration files
89+
* Add the following under the `scripts` key in `composer.json`:
90+
91+
```json
92+
"post-update-cmd": [
93+
"php bin/composer-post-install-script.php"
94+
],
95+
```
96+
97+
* Remove the following section from `.github/workflows/codecov.yml` and `.github/workflows/static-analysis.yml`
98+
99+
```yaml
100+
- name: Setup project
101+
run: |
102+
mv config/autoload/local.php.dist config/autoload/local.php
103+
mv config/autoload/mail.global.php.dist config/autoload/mail.global.php
104+
mv config/autoload/local.test.php.dist config/autoload/local.test.php
105+
```
106+
107+
> The command can be manually run via `php bin/composer-post-install-script.php`
108+
109+
### Update security.txt
110+
111+
* Add the `Preferred-Languages` key to `public/.well-known/security.txt`
112+
> You may include more than one language as comma separated language tags
113+
114+
### Update coding standards
115+
116+
* Bump `laminas/laminas-coding-standard` to `^3.0` in `composer.json`
117+
* Add the following to `phpcs.xml` to prevent issues with the fully qualified names from `config/config.php`:
118+
119+
```xml
120+
<rule ref="LaminasCodingStandard">
121+
<!-- Exclude rule -->
122+
<exclude name="SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly.ReferenceViaFullyQualifiedName" />
123+
</rule>
124+
```
125+
126+
### Fix codecov.yml
127+
128+
* Change `COMPOSER_DEV_MODE=1` to the correct syntax `COMPOSER_DEV_MODE: 1`
129+
130+
### Update Qodana configuration
131+
132+
* Update `.github/workflows/qodana_code_quality.yml`, specifying the supported PHP versions by adding the `strategy` key:
133+
134+
```yaml
135+
strategy:
136+
matrix:
137+
php-versions: [ '8.2', '8.3' ]
138+
```
139+
140+
* Update the `php-version` key to restrict Qodana to the newly added `php-versions`
141+
142+
Before:
143+
144+
```yaml
145+
with:
146+
php-version: "${{ matrix.php }}"
147+
```
148+
149+
After:
150+
151+
```yaml
152+
with:
153+
php-version: ${{ matrix.php-versions }}
154+
```
155+
156+
### Remove laminas/laminas-http
157+
158+
* Remove `laminas/laminas-http` from `composer.json`
159+
* Replace all uses of `Laminas\Http\Response` with `Fig\Http\Message\StatusCodeInterface` in `AuthorizationMiddlewareTest.php` and `ContentNegotiationMiddlewareTest.php`

0 commit comments

Comments
 (0)