Skip to content

changelog.rst

Latest commit

 

History

History
2014 lines (1468 loc) · 74.6 KB

changelog.rst

File metadata and controls

2014 lines (1468 loc) · 74.6 KB

Changelog

6.3.0+1

  • 👌 Allow setting parent_needs manually

    Use :parent_needs: PARENT_ID to assign a parent without actually nesting the needs in the source file.

6.3.0

Released:15.12.2025
Full Changelog:v6.2.0...v6.3.0

6.2.0

Released:28.11.2025
Full Changelog:v6.1.1...v6.2.0

This release introduces performance improvements for schema validation, to make it ~3 times faster (:pr:`1581`, :pr:`1582`, :pr:`1583`, :pr:`1584`).

This includes a change in dependencies, from jsonschema to jsonschema-rs for the core validation engine.

6.1.1

Released:25.11.2025
Full Changelog:v6.1.0...v6.1.1

This release focuses on schema validation improvements and bug fixes.

  • ✨ Add needs_schema_validation_enabled configuration (:pr:`1574`)

    New configuration option to disable schema validation entirely. This is set to True by default, for backward compatibility, and provides an opt-out mechanism when schema validation is not needed.

    See :ref:`needs_schema_validation_enabled` for more information.

  • ✨ Add allow_type_coercion configuration for external/import needs.json reads (:pr:`1573`)

    New configuration option for needs_external_needs and the needimport directive that controls whether field values should be automatically coerced to expected types. For example, enables/disables parsing comma-separated strings like "a,b,c" into list types like ["a", "b", "c"]. Set to True by default for backward compatibility. Setting to False may improve performance by skipping additional parsing.

    See :ref:`needs_external_needs` and :ref:`needimport` for more information.

  • 👌 Allow \. in schema regex patterns (:pr:`1568`)

    The regex pattern \. is now allowed in schema validations.

  • 🐛 Fix schema network type injection (:pr:`1570`)

    Fixed type injection mechanism that was failing for link types called contains or items. Constrained the injection to specific schema path structure locations.

  • 🐛 Fix needs.json schema for nullable fields (:pr:`1571`)

    Nullable fields now correctly reflect that property in the needs.json schemas section.

6.1.0

Released:31.10.2025
Full Changelog:v6.0.1...v6.1.0

Main focus of this release is the improvement of the schema severity handling.

  • 👌 Improve schema severity handling (:pr:`1561`)

    The PR removes the setting needs_schema_severity.

    All violations are printed to the console unless suppressed by suppress_warnings. To enable :ref:`granular warning suppression <suppress_validation_messages>`, the following warning types were added:

    • info: sn_schema_info
    • warning: sn_schema_warning
    • violation: sn_schema_violation

    The severities info and warning are logged as logger.warning(). The severity violation is logged as logger.error() so they appear as a different color in the output.

    The schema_violations.json file contains all violations, irrespective of the severity. Any downstream tool can filter for the required severity levels.

    In schema_violations.json, child elements do not contain log_lvl and type anymore to avoid duplication.

  • 👌 Make incoming / outgoing keys optional in needs_extra_links (:pr:`1548`)

    Defining a link is now possible with just needs_extra_links = [{"option": "links"}].

  • 🔧 Run new ubc action on docs (:pr:`1541`)

    A new GitHub action to run ubc is now used to lint all RST sources in the CI. Next step is to create a pre-commit hook for local usage.

Minor documentation updates and internal improvements:

  • 📚 Co-locate dynamic and variant function docs (:pr:`1544`)
  • 📚 Fix linkchecks (:pr:`1556`)
  • 📚 Improve schema docs (:pr:`1554`)
  • 📚 Enable link to full schema example (:pr:`1538`)
  • ♻ Early resolution of schema_debug_path (:pr:`1563`)
  • 🔧 Derive core FieldSchema from NeedsCoreFields (:pr:`1546`)
  • 🧪 Add snapshot test for field schema (:pr:`1545`)

6.0.1

Released:02.10.2025
Full Changelog:v6.0.0...v6.0.1

This release contains bug fixes for the 6.0.0 schema validation system and some minor improvements.

  • 👌 Add schema to add_extra_option :pr:`1527`

    Added schema parameter to :py:func:`add_extra_option <sphinx_needs.api.configuration.add_extra_option>` API to support typed fields in extensions that add extra options programmatically.

  • 🐛 Inject build_tags to variant filter strings :pr:`1531`

    Introduced a new context variable build_tags into :ref:`variant filter strings <needs_variant_support>` that contains all defined Sphinx build tags to be used as variant selector. The new variable can be used like this: 'tag1' in build_tags. This also avoids polluting the variable namespace with tags.

  • 🐛 Fix name error schema_path_contains :pr:`1530`

    Fixed bug when using contains validation on empty link lists.

  • 🔧 Fix schema json missing exc message :pr:`1526`

  • 🔧 Improve error for variant options :pr:`1524`

    Better error messages when variant options are incorrectly set to link types.

  • 📚 Add release labels to changelog :pr:`1523`

    Added stable release labels to changelog for better URL references.

6.0.0

Released:28.09.2025
Full Changelog:v5.1.0...v6.0.0

This release introduces strong typing for extra option fields to the Sphinx-Needs codebase. This affects needs read from RST sources (or others like .md), but also imported/exported needs of needs.json files.

The default type for extra options is still string, so existing configuration should work as before. Type errors are detected early once each need is fully resolved, i.e. after reading in the sources and evaluating :ref:`needs_global_options` (defaults), :ref:`needextend`, :ref:`variants <needs_variant_support>` and :ref:`dynamic_functions`. Errors in the typing system lead to needs not being created.

The release also introduces a new :ref:`schema_validation` system that integrates into the strong typing. It is JSON schema compliant in large parts with custom extensions to support network validation.

The core of Sphinx-Needs had to be refactored in large parts to enable these changes. The following are the main user-facing changes:

  • ♻️ Allow for typed needs_extra_options fields :pr:`1516`

    The needs_extra_options configuration option was extended to support schema information. The field schema.type globally sets the type for the field. Users can select between string, number (float), integer, boolean and array. For the array type another keyword schema.items.type defines the list items type.

    Examples in TOML configuration:

    [[needs.extra_options]]
name = "priority"
description = "Priority level, 1-5 where 1 is highest and 5 is lowest"
schema.type = "integer"
schema.minimum = 1
schema.maximum = 5

[[needs.extra_options]]
name = "asil"
description = "Automotive Safety Integrity Level"
schema.type = "string"
schema.enum = ["QM", "A", "B", "C", "D"]

    Key Changes:

    • Strong typing for needs_extra_options with JSON schema validation
    • Delayed resolution for dynamic functions, needextend, defaults, and variants
    • Automatic type coercion from string inputs (directive options) to proper types
    • Missing fields are set to None (null in JSON)
    • needs.json import/export with type validation and coercion; empty "" field values of existing needs.json files of type integer are coerced to 0, and for type number to 0.0 for backwards compatibility. Empty strings for boolean fields are coerced to True as this is often used as a flag.
    • Integration with schema validation system. The same fields for :ref:`supported_data_types` can be set in the definition, so they are set globally for that field.

    The implementation strives to be as backwards compatible as possible. See below for details.

  • ✨ Schema validation :pr:`1467`

    The PR adds a fast, declarative and versatile JSON schema based need validation. The schema is defined in the :ref:`needs_schema_definitions` configuration option or as JSON format passed via :ref:`needs_schema_definitions_from_json`.

    Key Features:

    • JSON Schema standard compliance using $defs and $ref for reusable sub-schemas
    • Fully typed implementation with runtime validation of schema definitions
    • Auto-injection of default string type when not specified
    • Select mechanism, comparable to database queries to select need nodes for validation.
    • Root validate key with local and network sub-sections for validation types. The split enables IDE extensions such as ubCode to validate-on-type for need-local changes and also run network validation once the index is fully built.
    • Debug mechanism using :ref:`needs_schema_debug_active` to check why validations pass or fail. 4 files are written per validation: original need, reduced need, applied schema and a result file with user and validation message. File naming pattern is <need_id>__<schema_path>__<validation_rule>.<json|txt>. Nested graph-validations are also dumped.
    • String regex pattern constraints with cross-engine compatibility
    • Semantic equivalence to JSON Schema spec for array items, minItems, maxItems, contains, minContains, and maxContains

    The new validation can replace :ref:`needs_warnings`, :ref:`needs_constraints`, :ref:`needs_id_regex`, :ref:`needs_statuses`, and :ref:`needs_tags` in the future.

    The implementation of the new strong typing and schema validation into ubCode is on the immediate roadmap.

  • 👌 Write schema violations into a JSON file :pr:`1503`

    Schema validation violations are now exported to a JSON file (schema_violations.json) for external tooling integration and automated quality assurance workflows. This enables CI/CD systems and external analysis tools to programmatically process validation results.

  • Always generate schema violations.json report file :pr:`1511`

These PRs were part of the internal changes:

  • 🧪 Move to snapshot testing for test_schema :pr:`1519`

  • 🔧 Add VariantFunctionParsed dataclass :pr:`1515`

  • 🔧 Add DynamicFunctionParsed dataclass :pr:`1514`

  • ♻️ Auto-compute certain need fields :pr:`1496`

  • ♻️ Set some core need fields to nullable :pr:`1488`

  • 🔧 Split import item filtering to separate function :pr:`1484`

  • ♻️ Lazily assess directive options :pr:`1482`

  • 🧪 Improve test for need parts :pr:`1507`

  • 👌 Improve need part processing :pr:`1469`

  • 🔧 Centralise allowed variant core need fields :pr:`1424`

  • ✨ Add is_import need field :pr:`1429`

    New field to identify needs that were imported from external sources.

Breaking Changes

  • :ref:`Variants <needs_variant_support>` have to be wrapped with << >>. This allows for a safer parsing strategy and support for usage in array elements.

  • The variant delimiter has changed to only allow ,. Formerly also ; was possible.

  • 🐛 Fix: disallow need variants for list type fields :pr:`1489`

    Variants no longer supported in list-type fields due to parsing instability. This feature might be re-introduced in future. The new syntax << >> would make this much easier.

  • ‼️ remove parsing of deprecated needs_global_options format :pr:`1517`

    Removes support for the deprecated legacy format of needs_global_options. The system now only accepts the dictionary format introduced in version 5.1.0. Projects using the old format will receive a warning that the configuration is not a dict and the parsing will be skipped entirely. Users must migrate to the new explicit format for global options to continue working.

  • ‼️ Improve needs default field application (via needs_global_options) :pr:`1478`

    Previously defaults would be applied to any fields of a need with a "falsy" value, e.g. None, False, 0, "", []. This is an issue if the user wants to specifically set fields to these values, without them being overridden by defaults. Therefore, now defaults are only applied to fields with a missing or None value.

  • ‼️ Disallow add_extra_option overriding an internal field :pr:`1477`

    Needs are stored in a flat dictionary as of now, so they cannot overlap.

  • ♻️ Store needs as NeedItem / NeedPartItem, rather than standard dict :pr:`1485`

    Replaces standard dictionary storage with specialized NeedItem and NeedPartItem classes. This allows better encapsulation and control over data mutation.

    This is breaking for any users doing "non-API" modifications or additions to the needs data, i.e. directly adding dict items. It should not change interactions with standard APIs like add_need or filter strings.

    These PRs are also related:

    • ♻️ Improve storage of part data on NeedItem :pr:`1509`
    • 🔧 Improve storage of content generation on NeedItem :pr:`1506`
    • 🔧 Improve storage of constraint results on NeedItem :pr:`1504`
    • 👌 Capture more information about modifications on NeedItem :pr:`1502`
    • ♻️ split off source fields in NeedItem internal data :pr:`1491`
    • ♻️ split NeedItem internal data into core, extras, links and backlinks :pr:`1490`

  • ⬆️ Drop Python 3.9 :pr:`1468`

  • ⬆️ Drop Sphinx<7.4, test against Python 3.13 :pr:`1447`

Further improvements and fixes

  • 🔧 Improve plantuml check + add tests :pr:`1521`

    PlantUML extension detection now uses app.extensions for better compatibility with dynamic registration. Thanks to @AlexanderLanin for the initial implementation.

  • ♻️ Warn for missing needimport files :pr:`1510`

    Missing :ref:`needimport` files now emit warnings instead of throwing exceptions, making it possible to ignore the problem for specific use cases.

  • 🐛 Avoid leaking auth credentials for ext. need warnings :pr:`1512`

  • ♻️ Exclude is_need / is_part from needs.json output :pr:`1505`

    It doesn't make sense to have these, since only needs are written, not parts. Also, these fields are "thrown away" when passing in external/import needs.json.

    These fields are only really used during processing, within filter contexts, when filtering across both needs and parts.

  • 👌 Reset directive option specs at start of build :pr:`1448`

    Internal fix to reset directive options for consistent builds & testing.

  • 🐛 Warn on dynamic function with surrounding text :pr:`1426`

    Added warning when dynamic functions are used for a list type with surrounding text as the surrounding text will be silently ignored.

  • Allow collapse and hide in needs_global_options :pr:`1456`

  • 🔧 Allow template global_options :pr:`1454`

  • 👌 Re-allow dynamic functions for layout field :pr:`1423`

  • 🔧 Allow pre/post template global_options :pr:`1428`

Minor documentation updates

Infrastructure

5.1.0

Released:06.03.2025
Full Changelog:v5.0.0...v5.1.0

The :ref:`needs_global_options` configuration option has been updated to a new format, to be more explicit and to allow for future improvements :pr:`1413`. The old format is currently still supported, but will emit a warning. Additionally, checks are put in place to ensure that the keys used are from the allowed set (:pr:`1410`).:

  • any needs_extra_options field
  • any needs_extra_links field
  • status
  • layout
  • style
  • tags
  • constraints
needs_global_options = {
   "field1": "a",
   "field2": ("a", 'status == "done"'),
   "field3": ("a", 'status == "done"', "b"),
   "field4": [
      ("a", 'status == "done"'),
      ("b", 'status == "ongoing"'),
      ("c", 'status == "other"', "d"),
   ],
}
needs_global_options = {
   "field1": {"default": "a"},
   "field2": {"predicates": [('status == "done"', "a")]},
   "field3": {
      "predicates": [('status == "done"', "a")],
      "default": "b",
   },
   "field4": {
      "predicates": [
            ('status == "done"', "a"),
            ('status == "ongoing"', "b"),
            ('status == "other"', "c"),
      ],
      "default": "d",
   },
}

5.0.0

Released:18.02.2025
Full Changelog:v4.2.0...v5.0.0

This release includes a number of changes, to bring more clarity to the needs data structure and post-processing steps. In most cases it should not be breaking, but may be in some corner cases.

  • ✨ Add c.this_doc() check for use in directive :filter: option :pr:`1393` and :pr:`1405`

    This allows for filtering of needs only in the same document as the directive itself, e.g.

    .. needextend:: c.this_doc() and status is None
   :status: open

    This works for all common filtered directives, see :ref:`filter_current_page`

  • ♻️ Remove full_title need field and only trim generated titles :pr:`1407`

    The existence of both title and full_title is confusing and unnecessary (in most cases these are equal), and so full_title is removed.

    Trimming (when :ref:`needs_max_title_length` is set) is now only applied to auto-generated titles, as per the documentation in :ref:`needs_title_from_content`

  • ♻️ Make needextend argument declarative :pr:`1391`

    The argument for needextend can refer to either a single need ID or filter function. Currently, the format cannot be known until all needs have been processed, and it is resolved during post-processing. This is problematic for (a) user readability, (b) improving processing performance and issue feedback

    This PR slightly modifies the argument processing to allow for two "explicit" formats:

    • <ID>, if the argument is enclosed in <> it is always processed as a single ID
    • "filter string", if the argument is enclosed in "" it is always processed as a filter string

    See :ref:`needextend` for more information.

  • ♻️ Remove back link manipulation from needextend :pr:`1386`

    Back links are computed at the end of the need post-processing, after needextend have been applied.

    Back links should always be in-sync with forward links, therefore it doesn't make sense to modify back links in this way.

  • ♻️ Do not process dynamic functions on internal need fields :pr:`1387` and :pr:`1406`

    For most "internal" need fields it does not make sense that these would be dynamic, and anyway this would fail since their values are not string types.

    Dynamic function processing is now skipped, for core fields that should not be altered by the user. The following fields are allowed to contain dynamic functions:

    • status
    • tags
    • style
    • constraints
    • all needs_extra_options
    • all needs_extra_links
    • all needs_global_options

  • ♻️ Remove delete from internal needs and needs.json :pr:`1347`

    The :delete: option on a need directive deletes a need before creating/storing it, therefore it is impossible for it to be anything other than False. Storing the field on a need is misleading, because it suggests that the need will be deleted, which is not possible with the current sphinx-needs logic.

  • 👌 Add type warnings of extra options in external/import reads :pr:`1389`

    Currently, the value of all extra options is expected to be a string; other types are not supported in various aspects of sphinx-needs (such as needextend, dynamic functions and filtering), and in-fact are already silently converted to strings during the reads.

    The warnings needs.mistyped_external_values and needs.mistyped_import_values are added for non-string values, for needs_external_needs and needimport sources respectively.

  • 🔧 Synchronize list splitting behaviour in need and needextend directives :pr:`1385`

4.2.0

Released:07.01.2025
Full Changelog:v4.1.0...v4.2.0
  • ⬆️ Drop Python 3.8 and Sphinx 6
  • ✨ Add :ref:`needs_import_keys` configuration :pr:`1379`
  • 👌 Allow filter-func in needpie to have multiple dots in the import path :pr:`1350`
  • 🐛 Make external paths relative to confdir, not srcdir :pr:`1378`
  • 🔧 Release needs data mutation lock at end of process :pr:`1359`
  • 🔧 Add lineno to default output of needs.json :pr:`1346`

4.1.0

Released:28.10.2024
Full Changelog:v4.0.0...v4.1.0

New

  • ✨ Add needs_from_toml configuration :pr:`1337`

    Configuration can now be loaded from a TOML file, using the needs_from_toml configuration option. See :ref:`needs_from_toml` for more information.

  • ✨ Allow configuring description of extra options in needs_extra_options :pr:`1338`

    The needs_extra_options configuration option now supports dict items with a name and description key, See :ref:`needs_extra_options` for more information.

Fixes

  • 🐛 Fix clickable links to needs in needflow, when using the graphviz engine :pr:`1339`
  • 🐛 Allow sphinx-needs to run without sphinxcontrib.plantuml installed :pr:`1328`
  • 🔧 Remove some internal fields from needs layout :pr:`1330`
  • 🔧 Merge defaults into user-defined configuration earlier (to avoid sphinx warnings) :pr:`1341`

4.0.0

Released:09.10.2024
Full Changelog:v3.0.0...v4.0.0

Breaking Changes

This commit contains a number of breaking changes:

Improvements to filtering at scale

For large projects, the filtering of needs in analytical directives such as :ref:`needtable`, :ref:`needuml`, etc, can be slow due to requiring an O(N) scan of all needs to determine which to include.

To address this, the storage of needs has been refactored to allow for pre-indexing of common need keys, such as id, status, tags, etc, after the read/collection phase. Filter strings such as id == "my_id" are then pre-processed to take advantage of these indexes and allow for O(1) filtering of needs, see the :ref:`filter_string_performance` section for more information.

This change has required changes to the internal API and stricter control on the access to and modification of need data, which may affect custom extensions that modified needs data directly:

  • Access to internal data from the Sphinx env object has been made private
  • Needs data during the write phase is exposed with either the read-only :class:`.NeedsView` or :class:`.NeedsAndPartsListView`, depending on the context.
  • Access to needs data, during the write phase, can now be achieved via :func:`.get_needs_view`
  • Access to mutable needs should generally be avoided outside of the formal means, but for back-compatibility the following :external+sphinx:ref:`Sphinx event callbacks <events>` are now available:
    • needs-before-post-processing: callbacks func(app, needs) are called just before the needs are post-processed (e.g. processing dynamic functions and back links)
    • needs-before-sealing: callbacks func(app, needs) just after post-processing, and before the needs are changed to read-only

Additionally, to identify any long running filters, the :ref:`needs_uml_process_max_time`, :ref:`needs_filter_max_time` and :ref:`needs_debug_filters` configuration options have been added.

Key changes were made in:

  • ♻️ Replace need dicts/lists with views (with fast filtering) in :pr:`1281`
  • 🔧 split filter_needs func by needs type in :pr:`1276`
  • 🔧 Make direct access to env attributes private in :pr:`1310`
  • 👌 Move sorting to end of process_filters in :pr:`1257`
  • 🔧 Improve process_filters function in :pr:`1256`
  • 🔧 Improve internal API for needs access in :pr:`1255`
  • 👌 Add needs_uml_process_max_time configuration in :pr:`1314`
  • ♻️ Add needs_filter_max_time / needs_debug_filters, deprecate export_id in :pr:`1309`

Improved warnings

sphinx-needs is designed to be durable and only except when absolutely necessary. Any non-fatal issues during the build are logged as Sphinx warnings. The warnings types have been improved and stabilised to provide more information and context, see :ref:`config-warnings` for more information.

Additionally, the :func:`.add_need` function will now only raise the singular exception :class:`.InvalidNeedException` for all need creation issues.

Key changes were made in:

  • 👌 Warn on unknown need keys in external/import sources in :pr:`1316`
  • ♻️ Extract generate_need from add_need & consolidate warnings in :pr:`1318`

Improved needs.json

A number of output need fields have been changed, to simplify the output. Key changes were made in:

  • 🔧 change type of need fields with bool | None to just bool in :pr:`1293`
  • ♻️ Remove target_id core need field in :pr:`1315`
  • ♻️ Output content in needs.json not description in :pr:`1312`
  • 👌 Add creator key to needs.json in :pr:`1311`

Replacement of [[...]] and need_func in need content

The parsing of the [[...]] dynamic function syntax in need content could cause confusion and unexpected behaviour. This has been deprecated in favour of the new, more explicit :ref:`ndf role <ndf>`, which also deprecates the need_func role.

See :pr:`1269` and :pr:`1266` for more information.

Removed deprecation

The deprecated needfilter directive is now removed (:pr:`1308`)

New and improved features

  • ✨ add tags option for list2need directive in :pr:`1296`
  • ✨ Add ids option for needimport in :pr:`1292`
  • 👌 Allow ref in needuml to handle need parts in :pr:`1222`
  • 👌 Improve parsing of need option lists with dynamic functions in :pr:`1272`
  • 👌 Improve warning for needextract incompatibility with external needs in :pr:`1325`
  • 🔧 Set env_version for sphinx extension in :pr:`1313`

Bug Fixes

  • 🐛 Fix removal of Needextend nodes in :pr:`1298`
  • 🐛 Fix usage numbers in needreport in :pr:`1285`
  • 🐛 Fix parent_need propagation from external/imported needs in :pr:`1286`
  • 🐛 Fix need_part with multi-line content in :pr:`1284`
  • 🐛 Fix dynamic functions in needextract need in :pr:`1273`
  • 🐛 Disallow dynamic functions [[..]] in literal content in :pr:`1263`
  • 🐛 fix parts defined in nested needs in :pr:`1265`
  • 🐛 Handle malformed filter-func option value in :pr:`1254`
  • 🐛 Pass needs to highlight filter of graphviz needflow in :pr:`1274`
  • 🐛 Fix parts title for needflow with graphviz engine in :pr:`1280`
  • 🐛 Fix need_count division by 0 in :pr:`1324`

3.0.0

Released:28.08.2024
Full Changelog:v2.1.0...v3.0.0

This release includes a number of new features and improvements, as well as some bug fixes.

Updated dependencies

  • sphinx: >=5.0,<8 to >=6.0,<9
  • requests: ^2.25.1 to ^2.32
  • requests-file: ^1.5.1 to ^2.1
  • sphinx-data-viewer: ^0.1.1 to ^0.1.5

Documentation and CSS styling

The documentation theme has been completely updated, and a tutorial added.

To improve sphinx-needs compatibility across different Sphinx HTML themes, the CSS for needs etc has been modified substantially, and so, if you have custom CSS for your needs, you may need to update it.

See :ref:`install_theme` for more information on how to setup CSS for different themes, and :pr:`1178`, :pr:`1181`, :pr:`1182` and :pr:`1184` for the changes.

needflow improvements

The use of Graphviz as the underlying engine for needflow diagrams, in addition to the default PlantUML, is now allowed via the global :ref:`needs_flow_engine` configuration option, or the per-diagram :ref:`engine <needflow_engine>` option.

The intention being to simplify and improve performance of graph builds, since plantuml has issues with JVM initialisation times and reliance on a third-party sphinx extension.

See :ref:`needflow` for more information, and :pr:`1235` for the changes.

additional improvements:

  • ✨ Allow setting an alt text for needflow images
  • ✨ Allow creating a needflow from a root_id in :pr:`1186`
  • ✨ Add border_color option for needflow in :pr:`1194`

needs.json improvements

A needs_schema is now included in the needs.json file (per version), which is a JSON schema for the data structure of a single need.

This includes defaults for each field, and can be used in combination with the :ref:`needs_json_remove_defaults` configuration option to remove these defaults from each individual need.

Together with the new automatic minifying of the needs.json file, this can reduce the file size by down to 1/8th of its previous size.

The :ref:`needs_json_exclude_fields` configuration option can also be used to modify the excluded need fields from the needs.json file, and backlinks are now included in the needs.json file by default.

See :ref:`needs_builder_format` for more information, and :pr:`1230`, :pr:`1232`, :pr:`1233` for the changes.

Additionally, the content_node, content_id fields are removed from the internal need data structure (see :pr:`1241` and :pr:`1242`).

Additional improvements

  • 👌 Capture filter processing times when using needs_debug_measurement=True in :pr:`1240`
  • 👌 Allow style and color fields to be omitted for needs_types items and a default used in :pr:`1185`
  • 👌 Allow collapse / delete / jinja_content directive options to be flags in :pr:`1188`
  • 👌 Improve need-extend; allow dynamic functions in lists in :pr:`1076`
  • 👌 Add collapse button to clean_xxx layouts in :pr:`1187`
  • 🐛 fix warnings for duplicate needs in parallel builds in :pr:`1223`
  • 🐛 Fix rendering of needextract needs and use warnings instead of exceptions in :pr:`1243` and :pr:`1249`

2.1.0

Released:08.05.2024
Full Changelog:v2.0.0...v2.1.0

Improvements

  • 👌 Default to warning for missing needextend ID in :pr:`1066`
  • 👌 Make needtable titles more permissive in :pr:`1102`
  • 👌 Add filter_warning directive option, to replace default warning text in :pr:`1093`
  • 👌 Improve and test github needservice directive in :pr:`1113`
  • 👌 Improve warnings for invalid filters (add source location and subtype) in :pr:`1128`
  • 👌 Exclude external needs from needs_id_regex check in :pr:`1108`
  • 👌 Fail and emit warning on filters that do not return a boolean result in :pr:`964`
  • 👌 Improve Need node creation and content parsing in :pr:`1168`
  • 👌 Add loading message to permalink.html in :pr:`1081`
  • 👌 Remove hard-coding of completion and duration need fields in :pr:`1127`

Bug fixes

  • 🐛 Image layout function in :pr:`1135`
  • 🐛 Centralise splitting of need ID in :pr:`1101`
  • 🐛 Centralise need missing link reporting in :pr:`1104`

Internal improvements

  • 🔧 Use future annotations in all modules in :pr:`1111`
  • 🔧 Replace black/isort/pyupgrade/flake8 with ruff in :pr:`1080`
  • 🔧 Add better typing for extra_links config variable in :pr:`1131`
  • 🔧 Centralise need parts creation and strongly type needs in :pr:`1129`
  • 🔧 Fix typing of need docname/lineno in :pr:`1134`
  • 🔧 Type ExternalSource config dict in :pr:`1115`
  • 🔧 Enforce type checking in needuml.py in :pr:`1116`
  • 🔧 Enforce type checking in api/need.py in :pr:`1117`
  • 🔧 Add better typing for global_options config variable in :pr:`1120`
  • 🔧 Move dead link need fields to internals in :pr:`1119`
  • 🔧 Remove usage of hide_status and hide_tags in :pr:`1130`
  • 🔧 Remove hidden field from extra_options in :pr:`1124`
  • 🔧 Remove constraints from extra_options in :pr:`1123`
  • 🔧 Remove use of deprecated needs_extra_options as dict in :pr:`1126`

2.0.0

Released:13.11.2023
Full Changelog:1.3.0...v2.0.0

This release is focussed on improving the internal code-base and its build time performance, as well as improved build warnings and other functionality improvements / fixes.

Changed

  • Add Sphinx 7 support and drop Python 3.7 (:pr:`1056`). Sphinx 5, 6, 7 and Python 3.8 to 3.11 are now fully supported and tested.
  • The matplotlib dependency (for needbar and needpie plots) is now optional, and should be installed with sphinx-needs[plotting], see :ref:`installation` (:pr:`1061`)
  • The NeedsBuilder format name is changed to needs (:pr:`978`)

New

Improved

Performance:

  • General performance improvement (up to 50%) and less memory consumption (~40%).
  • external_needs now uses cached templates to save generation time.
  • Improved performance for :ref:`needextend` with single needs.
  • Improved performance by memoizing the inline parse in build_need (:pr:`968`)
  • Remove deepcopy of needs data (:pr:`1033`)
  • Optimize needextend filter_needs usage (:pr:`1030`)
  • Improve performance of needs builders by skipping document post-transforms (:pr:`1054`)

Other:

Fixed

Internal

1.3.0

Released: 16.08.2023

1.2.2

Released: 08.02.2023

  • Bugfix: Changed needed version of jsonschema-lib to be not so strict. (:pr:`871`)

1.2.1

Released: 08.02.2023

1.2.0

Released: 24.01.2023

1.1.1

Released: 21.12.2022

  • Bugfix: Removed outdated JS codes that handles the collapse button. (:issue:`840`)
  • Improvement: Write autogenerated images into output folder (:issue:`413`)
  • Improvement: Added vector output support to need figures. (:issue:`815`).
  • Improvement: Introduce the jinja function ref for :ref:`needuml`. (:issue:`789`)
  • Bugfix: Needflow fix bug in child need handling. (:issue:`785`).
  • Bugfix: Needextract handles image and download directives correctly. (:issue:`818`).
  • Bugfix: Needextract handles substitutions correctly. (:issue:`835`).

1.1.0

Released: 22.11.2022

  • Bugfix: Expand/Collapse button does not work. (:issue:`795`).
  • Bugfix: singlehtml and latex related builders are working again. (:issue:`796`).
  • Bugfix: Needextend throws the same information 3 times as part of a single warning. (:issue:`747`).
  • Improvement: Memory consumption and runtime improvements (:issue:`790`).
  • Improvement: Obfuscate HTTP authentication credentials from log output. (:issue:`759`)
  • Bugfix: needflow: nested needs on same level throws PlantUML error. (:issue:`799`)

1.0.3

Released: 08.11.2022

1.0.2

Released: 22.09.2022

1.0.1

Released: 11.07.2022

  • Notice: Sphinx <5.0 is no longer supported.
  • Notice: Docutils <0.18.1 is no longer supported.
  • Improvement: Provides :ref:`needuml` for powerful, reusable Need objects.
  • Improvement: Provides :ref:`needreport` for documenting configuration used in a Sphinx-Needs project's conf.py.
  • Improvement: Provides initial support for Sphinx-Needs IDE language features. (:pr:`584`)
  • Improvement: Support snippet for auto directive completion for Sphinx-Needs IDE language features.
  • Improvement: Added show_top_sum to :ref:`Needbar <needbar>` and make it possible to rotate the bar labels. (:issue:`516`)
  • Improvement: Added needs_constraints option. Constraints can be set for individual needs and describe properties a need has to meet.
  • Improvement: Added customizable link text of :ref:`Need <needref>`. (#439)
  • Bugfix: Fixed lsp needs.json path check. (:issue:`603`, :issue:`633`)
  • Bugfix: Support embedded needs in embedded needs. (:issue:`486`)
  • Bugfix: Correct references in :ref:`needtables <needtable>` to be external or internal instead of always external.
  • Bugfix: Correct documentation and configuration in :ref:`need_tags` to list type.
  • Bugfix: Handle overlapping labels in :ref:`needpie`. (:issue:`498`)
  • Bugfix: :ref:`needimport` uses source-folder for relative path calculation (instead of confdir).

0.7.9

Released: 10.05.2022

0.7.8

Released: 29.03.2022

0.7.7

Released: 04.03.2022

  • Bugfix: need role supporting lower and upper IDs. (:issue:`508`)
  • Bugfix: Correct image registration to support build via Sphinx API. (:issue:`505`)
  • Bugfix: Correct css/js file registration on windows. (:issue:`455`)

0.7.6

Released: 28.02.2022

0.7.5

Released: 21.01.2022

0.7.4

Released: 30.11.2021

0.7.3

Released: 08.11.2021

0.7.2

Released: 08.10.2021

0.7.1

Released: 21.07.2021

0.7.0

Released: 06.07.2021

0.6.3

Released: 18.06.2021

0.6.2

Released: 30.04.2021

  • Improvement: Parent needs of nested needs get collected and are available in filters. (:issue:`249`)
  • Bugfix: Copying static files during sphinx build is working again. (:issue:`252`)
  • Bugfix: Link function for layouts setting correct text. (:issue:`251`)

0.6.1

Released: 23.04.2021

  • Support: Removes support for Sphinx version <3.0 (Sphinx 2.x may still work, but it gets not tested).
  • Improvement: Internal change to poetry, nox and github actions. (:issue:`216`)
  • Bugfix: Need-service calls get mocked during tests, so that tests don't need reachable external services any more.
  • Bugfix: No warning is thrown any more, if :ref:`needservice` can't find a service config in conf.py (:issue:`168`)
  • Bugfix: Needs nodes get ids set directly, to avoid empty ids given by sphinx or other extensions for need-nodes. (:issue:`193`)
  • Bugfix: :ref:`needimport` supports extra options and extra fields. (:issue:`227`)
  • Bugfix: Checking for ending / of given github api url. (:issue:`187`)
  • Bugfix: Using correct indention for pre and post_template function of needs.
  • Bugfix: Certain log message don't use python internal id any more. (:issue:`225`)
  • Bugfix: JS-code for meta area collapse is working again. (:issue:`242`)

0.6.0

0.5.6

  • Bugfix: Dynamic function registration via API supports new internal function handling (:issue:`147`)
  • Bugfix: Deactivated linked gantt elements in :ref:`needgantt`, as PlantUML does not support them in its latest version (not beta).

0.5.5

0.5.4

0.5.3

0.5.2

0.5.1

  • Improvement: Added :ref:`needextract` directive to mirror existing needs for special outputs. (:issue:`66`)
  • Improvement: Added new styles discreet and discreet_border.
  • Bugfix: Some minor css fixes for new layout system.

0.5.0

WARNING: This version changes a lot the html output and therefore the needed css selectors. So if you are using custom css definitions you need to update them.

0.4.3

0.4.2

0.4.1

0.4.0

  • Improvement: Provides API for other sphinx-extensions. See :ref:`api` for documentation.
  • Improvement: Added :ref:`support` page.
  • Bugfix: Fixed deprecation warnings to support upcoming Sphinx3.0 API.

0.3.15

  • Improvement: In filter operations, all needs can be accessed by using keyword needs.
  • Bugfix: Removed prefix from normal needs for needtable (:issue:`97`)

0.3.14

0.3.13

  • Bugfix: Filters on needs with id_parent or id_complete do not raise an exception any more and filters gets executed correctly.

0.3.12

0.3.11

0.3.10

0.3.9

  • Bugfix: Grubby tag/link strings in needs, which define empty links/tags, produce a warning now.
  • Bugfix: Better logging of document location, if a filter string is not valid.
  • Bugfix: Replaced all print-statements with sphinx warnings.

0.3.8

0.3.7

  • Improvement: :ref:`filter_string` now supports the filtering of :ref:`need_part`.
  • Improvement: The ID of a need is now printed as link, which can easily be used for sharing. (:issue:`75`)
  • Bugfix: Filter functionality in different directives are now using the same internal filter function.
  • Bugfix: Reused IDs for a :ref:`need_part` are now detected and a warning gets printed. (:issue:`74`)

0.3.6

0.3.5

  • Bugfix: A :ref:`need_part` without a given ID gets a random id based on its content now.
  • Bugfix: Calculation of outgoing links does not crash, if need_parts are involved.

0.3.4

  • Bugfix: Need representation in PDFs were broken (e.g. all meta data on one line).

0.3.3

  • Bugfix: Latex and Latexpdf are working again.

0.3.2

  • Bugfix: Links to parts of needs (:ref:`need_part`) are now stored and presented as links incoming of target link.

0.3.1

0.3.0

0.2.5

  • Bugfix: Fix for changes made in 0.2.5.

0.2.4

0.2.3

0.2.2

0.2.1

  • Bugfix: Sphinx warnings fixed, if need-collapse was used. (:issue:`46`)
  • Bugfix: dark.css, blank.css and common.css used wrong need-container selector. Fixed.

0.2.0

  • Deprecated: needfilter is replaced by :ref:`needlist`, :ref:`needtable` or :ref:`needflow`. Which support additional options for related layout.
  • Improvement: Added :ref:`needtable` directive.
  • Improvement: Added DataTables support for :ref:`needtable` (including table search, excel/pdf export and dynamic column selection).
  • Improvement: Added :ref:`needs_id_regex`, which takes a regular expression and which is used to validate given IDs of needs.
  • Improvement: Added meta information shields on documentation page
  • Improvement: Added more examples to documentation
  • Bugfix: Care about unneeded separator characters in tags (:issue:`36`)
  • Bugfix: Avoiding multiple registration of resource files (js, css), if sphinx gets called several times (e.g. during tests)
  • Bugfix: Needs with no status shows up on filters (:issue:`45`)
  • Bugfix: Supporting Sphinx 1.7 (:issue:`41`)

0.1.49

  • Bugfix: Supporting plantuml >= 0.9 (:issue:`38`)
  • Bugfix: need_outgoing does not crash, if given need-id does not exist (:issue:`32`)

0.1.48

  • Improvement: Added configuration option :ref:`needs_role_need_template`.
  • Bugfix: Referencing not existing needs will result in build warnings instead of a build crash.
  • Refactoring: needs development files are stored internally under sphinxcontrib/needs, which is in sync with
    most other sphinxcontrib-packages.

0.1.47

  • Bugfix: dark.css was missing in MANIFEST.in.
  • Improvement: Better output, if configured needs_css file can not be found during build.

0.1.46

  • Bugfix: Added python2/3 compatibility for needs_import.

0.1.45

  • Bugfix: needs with no status are handled the correct way now.

0.1.44

  • Bugfix: Import statements are checked, if Python 2 or 3 is used.

0.1.43

  • Improvement: Added "dark.css" as style
  • Bugfix: Removed "," as as separator of links in need presentation.

0.1.42

  • Improvement: Added config parameter :ref:`needs_css`, which allows to set a css file.
  • Improvement: Most need-elements (title, id, tags, status, ...) got their own html class attribute to support custom styles.
  • Improvement: Set default style "modern.css" for all projects without configured :ref:`needs_css` parameter.

0.1.41

0.1.40

  • Bugfix: Removed jinja activation

0.1.39

  • Bugfix: Added missing needimport_template.rst to package
  • Bugfix: Corrected version param of needimport

0.1.38

  • Improvement: :links:, :tags: and other list-based options can handle "," as delimiter
    (beside documented ";"). No spooky errors are thrown any more if "," is used accidentally.

0.1.37

0.1.36

  • Bugfix: Empty :links: and :tags: options for :ref:`need` raise no error during build.

0.1.35

  • Improvement/Bug: Updated default node_template to use less space for node parameter representation
  • Improvement: Added :filter: option to :ref:`needimport` directive
  • Bugfix: Set correct default value for need_list option. So no more warnings should be thrown during build.
  • Bugfix: Imported needs gets sorted by id before adding them to the related document.

0.1.34

  • Improvement: New option tags for :ref:`needimport` directive
  • Bugfix: Handling of relative paths in needs builder

0.1.33

  • New feature: Directive :ref:`needimport` implemented
  • Improvement: needs-builder stores needs.json for all cases in the build directory (like _build/needs/needs.json) (See issue)
  • Bugfix: Wrong version in needs.json, if an existing needs.json got imported
  • Bugfix: Wrong need amount in initial needs.json fixed

0.1.32

  • Bugfix: Setting correct working directory during conf.py import
  • Bugfix: Better config handling, if Sphinx builds gets called multiple times during one single python process. (Configs from prio sphinx builds may still be active.)
  • Bugifx: Some clean ups for using Sphinx >= 1.6

0.1.31

  • Bugfix: Added missing dependency to setup.py: Sphinx>=1.6

0.1.30

0.1.29

  • Bugfix: Build has crashed, if sphinx-needs was loaded but not a single need was defined.

0.1.28

  • Bugfix: Added support for multiple sphinx projects initialisations/builds during a single python process call.
    (Reliable sphinx-needs configuration separation)

0.1.27

0.1.26

0.1.25

0.1.24

  • Bugfix: Reactivated jinja execution for documentation.

0.1.23

0.1.22

  • Improvement: needfilter directives supports complex filter-logic by using parameter :ref:`filter`.

0.1.21

  • Improvement: Added word highlighting of need titles in linked pages of svg diagram boxes.

0.1.20

  • Bugfix for custom needs_types: Parameter in conf.py was not taken into account.

0.1.19

  • Added configuration parameter :ref:`needs_id_required`.
  • Backwards compatibility changes:
  • Reimplemented needlist as alias for needfilter
  • Added need directive/need as part of the default :ref:`needs_types` configuration.

0.1.18

Initial start for the changelog

  • Free definable need types (Requirements, Bugs, Tests, Employees, ...)
  • Allowing configuration of needs with a
  • directive name
  • meaningful title
  • prefix for generated IDs
  • color
  • Added needfilter directive
  • Added layouts for needfilter:
  • list (default)
  • table
  • diagram (based on plantuml)
  • Integrated interaction with the activated plantuml sphinx extension
  • Added role need to create a reference to a need by giving the id