From 4dc14b44e94d40a637bd59919f32091de9b9d45e Mon Sep 17 00:00:00 2001 From: Stanislav Pankevich Date: Tue, 18 Jun 2024 21:35:17 +0200 Subject: [PATCH] docs: prepare the release notes for FREETEXT-TEXT migration --- docs/strictdoc_04_release_notes.sdoc | 57 ++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/docs/strictdoc_04_release_notes.sdoc b/docs/strictdoc_04_release_notes.sdoc index 6f5e5f2f1..8da1b0ea2 100644 --- a/docs/strictdoc_04_release_notes.sdoc +++ b/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 `_. [/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)