Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: prepare the release notes for FREETEXT-TEXT migration #1875

Merged
merged 1 commit into from
Jun 18, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
57 changes: 57 additions & 0 deletions docs/strictdoc_04_release_notes.sdoc
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down