Merge pull request strictdoc-project#1875 from strictdoc-project/stan…

…islaw/html_markup_tweak

docs: prepare the release notes for FREETEXT-TEXT migration

docs/strictdoc_04_release_notes.sdoc

@@ -5,6 +5,63 @@ TITLE: Release Notes
 This document maintains a record of all changes to StrictDoc since November 2023. It serves as a user-friendly version of the changelog, complementing the automatically generated, commit-by-commit changelog available here: `StrictDoc Changelog <https://github.com/strictdoc-project/strictdoc/blob/main/CHANGELOG.md>`_.
 [/FREETEXT]
 
+[SECTION]
+TITLE: Not released yet
+
+[TEXT]
+STATEMENT: >>>
+This release contains a significant, non-breaking change that affects the entire StrictDoc codebase and the SDoc data model: the ``FREETEXT-TEXT`` migration.
+
+A new grammar node called ``TEXT`` has been introduced in the SDoc grammar, replacing the ``FREETEXT`` node as a more powerful feature.
+
+The reasons for the migration:
+
+- The ``[FREETEXT]..[/FREETEXT]`` markup element is limited. Unlike ``REQUIREMENT`` it is not possible to attach fields like MID or UID, which can be important for change tracking and importing/exporting from formats like ReqIF and SPDX, which assign unique identifiers to all nodes of the document / requirements graph, not just the requirements nodes.
+- Historically, the ``[FREETEXT]`` node was implemented differently compared to the ``REQUIREMENT`` node, creating a lot of branching and requiring two separate sets of code to handle free text and requirements slightly differently.
+- 15000 lines of code are removed, eliminating numerous branches, such as ``if node.is_requirement ... elif node.is_free_text``.
+
+The backward compatibility is preserved. The users can still create SDoc documents with ``FREETEXT`` but internally the free text nodes will be anyway converted to ``TEXT`` nodes. Users are encouraged to perform the migration as follows.
+
+The free text node:
+
+.. code-block::
+
+    [FREETEXT]
+    This is a free text node.
+    [/FREETEXT]
+
+becomes
+
+.. code-block::
+
+    [TEXT]
+    STATEMENT: >>>
+    This is a free text node.
+    <<<
+
+The ``TEXT`` node is now included to a default StrictDoc grammar by default. If a custom grammar is used, the default grammar definition for the ``TEXT`` node is as follows:
+
+.. code-block::
+
+    [GRAMMAR]
+    ELEMENTS:
+    - TAG: TEXT
+      FIELDS:
+      - TITLE: UID
+        TYPE: String
+        REQUIRED: False
+      - TITLE: STATEMENT
+        TYPE: String
+        REQUIRED: True
+    - TAG: REQUIREMENT
+    ... REQUIREMENT fields
+    ... Optionally other elements definitions.
+
+One outcome of this migration is that the ``TEXT`` nodes can have ``UID`` (if declared in a grammar) and ``MID`` (if the ``ENABLE_MID: True`` option is enabled), but the automatic generation of UIDs is disabled for ``TEXT`` nodes in the first version after the migration. User feedback regarding the potential use cases for ``TEXT`` node's UID/MID identifiers would be appreciated.
+<<<
+
+[/SECTION]
+
 [SECTION]
 TITLE: 0.0.56 (2024-06-02)