chore: mention a workaround for a pdd bug with single line HTML comments

[skip ci]

Author: php-coder

docs/decisions-log.md

@@ -8,7 +8,7 @@
 | 20.07.2023 Decision | [php-coder/mystamps#1154](https://github.com/php-coder/mystamps/issues/1154): some time ago (29.11.2022) **Travis CI** [stopped to work](https://github.com/php-coder/mystamps/issues/1154#issuecomment-1330014938) because of the changes in their policy. On 04.12.2022 [I contacted with support and got 25k credits](https://github.com/php-coder/mystamps/issues/1154#issuecomment-1336413246) and CI has started to work again. This was a signal to try **GitHub Actions** as it's more stable, feature-rich and native for GitHub. Today (20.07.2023) a migration has finished and the project now is fully moved to GitHub Actions |
 | 22.06.2023 Workaround | [php-coder/mystamps#1610](https://github.com/php-coder/mystamps/issues/1610): in the `connect-todos-to-issues.sh` script, we want to search issues that a) contains puzzle id in their body b) has a title like we have in a puzzle. The former condition covers the case when a puzzle id already has a related issue. The latter is for the case when puzzle id got changed but the title remains the same (for example, because of changing an intepretation of the comments) -- this is how we try to find an issue that was connected to an old puzzle. The limitation that I faced is that **`gh`** utility can't use *logical OR* in the search conditions. I added a workaround where we first search in body, after that by title, and at the end we merge the results together. Commit: [c02dc39a](https://github.com/php-coder/mystamps/commit/c02dc39a7357d30e8c8f74c346e5fc4b81122140) |
 | 22.06.2023 Workaround | [php-coder/mystamps#1610](https://github.com/php-coder/mystamps/issues/1610): in the `connect-todos-to-issues.sh` script, we use [**`gh`** cli tool](https://cli.github.com) for searching issues by its title. But it's turned out that it searches issues with titles that contain a phrase while we need an *exact match*. Discussion: [link](https://github.com/orgs/community/discussions/17956) Commit: [c02dc39a](https://github.com/php-coder/mystamps/commit/c02dc39a7357d30e8c8f74c346e5fc4b81122140)<br />UPDATE(28.06.2023): I'm going to add a workaround for that by filtering out the titles within the script. Commit: [1c5c0c2b](https://github.com/php-coder/mystamps/commit/1c5c0c2bd94d083114e05f0d43d4bfb727e84125) Issue: [#1618](https://github.com/php-coder/mystamps/issues/1618) |
-| 16.06.2023 Workaround | [php-coder/mystamps#1610](https://github.com/php-coder/mystamps/issues/1610): in one of the releases **pdd** has changed it's behavior for parsing of the multiline comments: previously, in order to be included in a title, the next line should have started from a space. The current behavior is that pdd reads all the next lines until a comment ends or the next puzzle appears. I had to modify the existing comments in order to make their titles look as expected. I also submitted an issue to the upstream in order to improve documentation regarding these rules. Commits: [c2adb2aa](https://github.com/php-coder/mystamps/commit/c2adb2aad0ea58a1aee85cbe4aa5838dfb70f510) Issue: [cqfn/pdd#224](https://github.com/cqfn/pdd/issues/224) |
+| 16.06.2023 Workaround | [php-coder/mystamps#1610](https://github.com/php-coder/mystamps/issues/1610): in one of the releases **pdd** has changed it's behavior for parsing of the multiline comments: previously, in order to be included in a title, the next line should have started from a space. The current behavior is that pdd reads all the next lines until a comment ends or the next puzzle appears. I had to modify the existing comments in order to make their titles look as expected. I also submitted an issue to the upstream in order to improve documentation regarding these rules. Commits: [c2adb2aa](https://github.com/php-coder/mystamps/commit/c2adb2aad0ea58a1aee85cbe4aa5838dfb70f510) Issue: [cqfn/pdd#224](https://github.com/cqfn/pdd/issues/224)<br />UPDATE(26.01.2025): I had to apply this workaround once again. Commits: [4599ec6](https://github.com/php-coder/mystamps/commit/4599ec61a7a4447c1b5cb099ba2a92e2d5701e53) |
 | 16.06.2023 Workaround | [php-coder/mystamps#1610](https://github.com/php-coder/mystamps/issues/1610): **pdd** incorrectly parses single line HTML comments and doesn't remove a trailing `-->` characters. They are being included in a title and it looks ugly. I have already reported that issue a few years back, but the issue got closed with a suggestion to modify the comments and make them multiline. I followed that advice and modified the comments. Commits: [20b47a73](https://github.com/php-coder/mystamps/commit/20b47a733533bfdd93164a1fd77e6f23e03a1ea2) Bug: [cqfn/pdd#111](https://github.com/cqfn/pdd/issues/111) |
 | ~~12.06.2023 Workaround~~ | ~~[php-coder/mystamps#1610](https://github.com/php-coder/mystamps/issues/1610): in order to work with `pdd.xml` that is generated by **pdd**, I needed a simple cli tool. I'd like to use `jq` for that purpose, but pdd doesn't support JSON as an output format. I created a feature request for that and I also wrote `pdd-xml-to-json.sh` to use as a workaround. Despite that later I have decided to use TSV as a primary format, I still use JSON as an intermediary format. Commits: [597aabf5](https://github.com/php-coder/mystamps/commit/597aabf5c2ca7f5406d81fed067e5e49dc91af1f) Issue: [cqfn/pdd#223](https://github.com/cqfn/pdd/issues/223)~~<br />UPDATE(27.05.2024): the script was removed after upgrading pdd to 0.24.0 that supports JSON format. Commits: [3bf056f6](https://github.com/php-coder/mystamps/commit/3bf056f69d146f735cfc198572ff524112f22737), [b7a7af8f](https://github.com/php-coder/mystamps/commit/b7a7af8f130c023240de46320d1712d7275f2ada), [33d062c8](https://github.com/php-coder/mystamps/commit/33d062c8e7149311050f3379a3504de987fa19be), [f25ef349](https://github.com/php-coder/mystamps/commit/f25ef3494e4b32fddfc44308f976bf75704f2718), [2e869e4b](https://github.com/php-coder/mystamps/commit/2e869e4b073b589ab9254d5eace49d958509b1e4) |
 | 30.05.2023 Decision | [php-coder/mystamps#1595](https://github.com/php-coder/mystamps/issues/1595): The rate of issues that I faced with pdd/**0pdd** is too high. Time to time, it tries to create the duplicated issues or close issues while the comments are still in place. Also the issues that have been reported to upstream didn't have reaction from the maintainers for a long time. I decided that its cons overweight the pros and I dicontinued a usage of 0pdd. At the same time, the approach is still seems useful so I'm going to create my own solution that will be based on pdd and Github Actions (see [php-coder/mystamps#1610](https://github.com/php-coder/mystamps/issues/1610)). While pdd also has bugs and it isn't actively maintained, neverthereless I can fix the code by myself or I will be able to add workarounds if needed. |