🚀 Release v8.0.0 (useblocks#1688)

Author: chrisjsewell

.github/workflows/docker.yaml

@@ -16,7 +16,7 @@ on:
     paths: ['docker/**']
 
 env:
-  NEEDS_VERSION: 7.0.0
+  NEEDS_VERSION: 8.0.0
   DEPLOY_IMAGE: ${{ github.event_name != 'pull_request' }}
 
 jobs:

docs/_static/tutorial_needs.json

@@ -48,7 +48,7 @@ This is a JSON schema of for the data structure of a single need,
 and also includes a ``field_type`` for each field, to denote the source of the field,
 that can be one of: ``core``, ``links``, ``backlinks``, ``extra``, ``global``.
 
-See also :ref:`needs_json_exclude_fields`, :ref:`needs_json_remove_defaults`, and :ref:`needs_reproducible_json` for more options on modifying the content of the ``needs.json`` file.
+See also :ref:`needs_json_exclude_fields`, :ref:`needs_json_remove_defaults`, :ref:`needs_reproducible_json`, and :ref:`needs_json_include_link_conditions` for more options on modifying the content of the ``needs.json`` file.
 
 .. note:: ``needs_defaults_removed`` is a flag that is set to ``true`` if the defaults are removed from the needs. If it is missing or set to ``false``, the defaults are not removed.
 

docs/builders.rst

@@ -4,13 +4,166 @@
 Changelog
 =========
 
+.. _`release:8.0.0`:
+
+8.0.0
+-----
+
+:Released: Unreleased
+:Full Changelog: `v7.0.0...v8.0.0 <https://github.com/useblocks/sphinx-needs/compare/7.0.0...5b223fd71eeb7402d5b60c1a5832434d8fd05e31>`__
+
+This release introduces **conditional link assessment** — the ability to attach
+:ref:`filter_string` conditions to links that are checked against the target need at build time.
+It also overhauls the internal link representation and fixes ``links_from_content`` to
+use the parsed doctree instead of fragile regex matching.
+
+Conditional link assessment
+...........................
+
+A major motivation for requirements-management tooling is ensuring traceability —
+not just *that* two needs are linked, but that the link is **valid in context**.
+For example, a specification should only link to requirements that are in an
+``"open"`` or ``"approved"`` state, or a test should only reference an implementation
+at a compatible version.
+
+Sphinx-Needs now supports this via **inline conditions** on link references
+(see :ref:`need_conditional_links`).
+Append a :ref:`filter_string` in square brackets after the target ID:
+
+.. code-block:: rst
+
+   .. spec:: My Specification
+      :links: REQ_001[status=="open"], REQ_002[version>=3]
+
+Each condition is evaluated against the **target** need's fields.
+If a condition evaluates to ``False``, a ``needs.link_condition_failed`` warning is emitted;
+if the condition syntax is invalid, a ``needs.link_condition_invalid`` warning is emitted.
+Links without conditions continue to work exactly as before.
+
+The condition is a standard :ref:`filter_string` expression, so you can use any Python-style
+comparison operators (``==``, ``!=``, ``>``, ``<``, ``>=``, ``<=``), membership checks
+(``in``, ``not in``), boolean connectives (``and``, ``or``, ``not``), and built-in helpers
+like ``search()``.
+
+This means conditions already work with **numeric fields** such as ``integer`` or ``number``
+(decimal) types. For example, if you define a ``version`` field:
+
+.. code-block:: toml
+
+   [needs.fields.version]
+   schema.type = "integer"
+   nullable = false
+
+You can then enforce version constraints on links:
+
+.. code-block:: rst
+
+   .. spec:: My Specification
+      :links: REQ_001[version>=2]
+
+When the condition contains square brackets (e.g. for list indexing), use multiple opening
+brackets — the parser matches N opening ``[`` with N closing ``]``:
+``REQ_001[[tags[0]=="important"]]``.
+
+- ✨ Add conditional need link assessment (:pr:`1675`)
+- ♻️ Add ``_split_link_list`` parser with condition syntax support (:pr:`1674`)
+- 👌 Parse link conditions from imported and external needs (:pr:`1680`)
+- 👌 Add :ref:`needs_json_include_link_conditions` config option (:pr:`1681`)
+
+  Controls whether conditions are included in ``needs.json`` output (default: ``True``).
+  Backlink fields are never affected.
+
+- 👌 Add ``parse_conditions`` configuration for link types (:pr:`1684`)
+
+  Per-link-type control over whether ``[condition]`` brackets are parsed.
+  Set ``parse_conditions = false`` on a link type to treat brackets as literal ID text.
+
+  .. code-block:: toml
+
+     [needs.links.raw_links]
+     parse_conditions = false
+
+.. note::
+
+   **Potential future directions**:
+
+   - **Hash-based checks**: combined with a ``hash`` field and a dynamic function that
+     computes a content hash, conditions like ``REQ_001[hash=="abc123"]`` could detect
+     when a linked need's content has changed since the link was authored.
+   - **Semantic version comparisons**: a dedicated semver field type would enable
+     conditions like ``REQ_001[version~=">=1.2.0"]`` with proper semver semantics.
+   - **Terse constraint syntax**: a more compact notation (e.g. ``REQ_001[s=open,v>=2]``
+     with field shorthands) is under consideration for common cases, but would
+     complement — not replace — the current filter-string syntax.
+
+``links_from_content`` rewrite
+..............................
+
+The ``links_from_content`` dynamic function previously used a regex to
+extract ``:need:`ID``` references from raw RST source text.
+This was fragile and could not handle custom titles (e.g. ``:need:`My Title <REQ_001>```),
+nested content, or other edge cases.
+
+It now walks the **parsed doctree** for the source need, collecting ``NeedRef`` nodes
+directly. This is more robust and correctly handles all role syntax variants.
+
+**Limitations**: ``links_from_content`` requires a stored doctree node.
+It will emit a warning and return an empty list for:
+
+- **External needs** (loaded via ``needimport`` / ``needs_external_needs``) — they have no doctree.
+- **Need parts** — not supported; a warning is emitted.
+
+- ♻️ Fix ``links_from_content`` to use parsed doctree nodes instead of regex (:pr:`1685`)
+
+Breaking changes
+................
+
+- ‼️ ``ENV_DATA_VERSION`` bumped to 4 (:pr:`1683`)
+
+  The internal format for storing link data in the Sphinx build environment has changed
+  (links are now stored as structured ``NeedLink`` objects instead of plain strings).
+  **Incremental builds from a previous version will trigger a full rebuild automatically.**
+
+- ‼️ ``need["links"]`` (and other link fields) now returns a fresh ``list[str]`` copy
+  rather than a reference to the internal storage (:pr:`1670`)
+
+  Previously, code like ``need["links"].append("NEW_ID")`` would mutate the internal list.
+  This now **silently has no effect** — the returned list is a projection from the internal
+  ``NeedLink`` representation. This should only affect exotic use cases such as dynamic
+  functions or custom extensions that mutate link lists via ``__getitem__`` access.
+  Use the ``NeedItem`` API (e.g. ``get_links(as_str=False)``) for direct access to the
+  internal ``NeedLink`` objects.
+
+Internal changes
+................
+
+These changes do not affect user-facing behaviour but improve link handling internals:
+
+- ♻️ Introduce ``NeedLink`` structured internal representation for links (:pr:`1670`)
+- ♻️ Store ``NeedLink`` instead of ``str`` in ``LinksLiteralValue`` and ``LinksFunctionArray`` (:pr:`1673`)
+- 🔧 Use ``NeedLink`` directly in ``update_back_links`` function (:pr:`1672`)
+- 🔧 Store ``NeedPartData.backlinks`` as ``NeedLink`` instead of ``str`` (:pr:`1679`)
+- 🔧 Use ``get_links(as_str=False)`` in needextend to avoid round-trip serialization (:pr:`1678`)
+- ♻️ Store ``NeedLink`` on ``NeedRef`` node at parse time instead of re-parsing later (:pr:`1682`)
+- 🧪 Add tests for variants in links (:pr:`1669`)
+
+Bug fixes
+.........
+
+- 🐛 Fix linkcheck CI job warnings (:pr:`1667`)
+
+Documentation
+.............
+
+- 📚 Add sphinx-ai-index to Sphinx docs builder (:pr:`1671`)
+
 .. _`release:7.0.0`:
 
 7.0.0
 -----
 
 :Released: 24.02.2026
-:Full Changelog: `v6.3.0...v7.0.0 <https://github.com/useblocks/sphinx-needs/compare/6.3.0...0aea09eda386880272205cbdc8a98fde3ff3566a>`__
+:Full Changelog: `v6.3.0...v7.0.0 <https://github.com/useblocks/sphinx-needs/compare/6.3.0...7.0.0>`__
 
 This is a major release that consolidates field, link, and default configuration
 into a single, composable schema system — inspired by
@@ -264,7 +417,7 @@ Documentation fixes
 -----
 
 :Released: 15.12.2025
-:Full Changelog: `v6.2.0...v6.3.0 <https://github.com/useblocks/sphinx-needs/compare/6.2.0...f567c1fafb4e1ba1a7dabb3bd6afc5f17ded84cd>`__
+:Full Changelog: `v6.2.0...v6.3.0 <https://github.com/useblocks/sphinx-needs/compare/6.2.0...6.3.0>`__
 
 - ⬆️ Support Python 3.14 (:pr:`1598`)
 - ♻️ Remove ``typeguard`` dependency (:pr:`1597`)

docs/changelog.rst

@@ -383,7 +383,7 @@ Each configured link can define:
 - ``parse_dynamic_functions``: If set to ``True``, the field will support :ref:`dynamic_functions`.
     Default: the value of :ref:`needs_parse_dynamic_functions` (``True``).
 - ``parse_conditions``: If set to ``False``, the ``[condition]`` bracket syntax will not be parsed for this link type.
-    Default: ``True``.
+    Default: ``True``. *New in version 8.0.0.*
 - ``incoming`` (optional): Incoming text, to use for incoming links. E.g. "is blocked by". Default: "<name> incoming".
 - ``outgoing`` (optional): Outgoing text, to use for outgoing links. E.g. "blocks". Default: "<name>".
 - ``copy`` (optional): True/False. If True, the links will be copied also to the common link-list (link type ``links``).
@@ -2833,7 +2833,7 @@ Each configured link should define:
 - ``parse_dynamic_functions``: If set to ``True``, the field will support :ref:`dynamic_functions`.
     Default: the value of :ref:`needs_parse_dynamic_functions` (``True``).
 - ``parse_conditions``: If set to ``False``, the ``[condition]`` bracket syntax will not be parsed for this link type.
-    Default: ``True``.
+    Default: ``True``. *New in version 8.0.0.*
 - ``incoming`` (optional): Incoming text, to use for incoming links. E.g. "is blocked by".
 - ``outgoing`` (optional): Outgoing text, to use for outgoing links. E.g. "blocks".
 - ``copy`` (optional): True/False. If True, the links will be copied also to the common link-list (link type ``links``).

docs/configuration.rst

@@ -133,6 +133,11 @@ conditional links
 
 .. versionadded:: 8.0.0
 
+In requirements management, traceability is not just about *whether* two needs are linked,
+but whether the link is **valid in context**.
+For example, a specification should only link to requirements that are ``"open"`` or ``"approved"``,
+or a test should only reference an implementation at a compatible version.
+
 You can attach a condition to any link by appending a :ref:`filter_string` in square brackets after the target ID.
 The condition is evaluated against the **targeted** need.
 If the condition evaluates to ``False``, a warning is emitted with the subcode ``needs.link_condition_failed``.
@@ -180,6 +185,10 @@ Links without conditions continue to work as before:
    ``"links": ["REQ_001[status==\"open\"]"]``
    and the condition will be evaluated during the build just as it would for a directive-defined link.
 
+.. seealso::
+
+   :ref:`needs_json_include_link_conditions` — controls whether conditions are included in ``needs.json`` output.
+
 extra links
 +++++++++++
 

docs/directives/need.rst

@@ -105,6 +105,7 @@ Filter string
 
 The usage of a filter string is supported/required by:
 
+* :ref:`Conditional links <need_conditional_links>` (to assert properties of a link target)
 * :ref:`need_count`
 * :ref:`needlist`
 * :ref:`needtable`

docs/filter.rst

@@ -42,6 +42,13 @@ content = false
 parse_content = false
 content_required = false
 
+[parse.extend_directives.need-core-fields]
+argument = false
+options = false
+content = false
+parse_content = false
+content_required = false
+
 [parse.extend_directives.page-summary]
 argument = false
 options = false

docs/ubproject.toml

@@ -1,6 +1,6 @@
 """Sphinx needs extension for managing needs/requirements and specifications"""
 
-__version__ = "7.0.0"
+__version__ = "8.0.0"
 
 
 def setup(app):  # type: ignore[no-untyped-def]

sphinx_needs/__init__.py

@@ -430,7 +430,11 @@ def links_from_content(
 
     Same links are only added once.
 
-    .. note::
+    .. versionchanged:: 8.0.0
+
+       Previously used a regex on raw RST source text to extract ``:need:`` references.
+       Now walks the parsed doctree, which correctly handles custom titles
+       (e.g. ``:need:`My Title <REQ_001>```) and nested content.
 
        This function requires the source need to have a stored doctree node.
        It will emit a warning and return an empty list for needs without a