Changelog

0.18.0

Released:

02.06.2026

Breaking

  • 💥 from-github filter fields moved out of the TOML config and onto the CLI. [ubconnect.from_github_issues] no longer accepts milestone or labels; configs carrying either fail with a Pydantic extra-forbidden validation error. Pass filters per run via --milestone, --label (repeatable), and the new --issue (repeatable, accepts bare issue numbers or full issue URLs). See GitHub Issues.

  • 💥 The canonical form of the :issue: field is now a list of integers (e.g. :issue: 42, 43) so a need can track multiple linked GitHub issues. Legacy single-integer values still parse on read for backwards compatibility, but new writers (from-github, to-github, sync-issue-refs) emit the list form.

New and Improved

  • ✨ Added a Jira Cloud connector: ubconnect jira from-jira imports Jira issues into the canonical needs.json envelope. Streams JQL-based pagination with retry-after-aware backoff, maps custom fields and issue links into typed need fields, and translates Jira wiki and Atlassian Document Format (ADF) bodies to RST. See Jira connector.

  • ✨ Added ubconnect wizard — an interactive, schema-driven setup command that generates a valid ubproject.toml. The wizard registry covers github, csv, reqif, and to-github; the wizard core supports nested TOML shapes (submodels, dicts of submodels, arrays of tables) so connectors using Pydantic submodels can register without renderer work. Each prompt shows the field description, marks the field required or optional, and shows the default where one exists; configuration sections are introduced with a header. Supports headless mode (--no-prompt --answers <file>), printing without writing (--print-config), and in-place editing of an existing ubproject.toml (--edit) that preserves comments, formatting, and non-wizard tables. See Setup Wizard.

  • ✨ Added a SourceAdapter extension point to the wizard: a connector can register an adapter that discovers runtime metadata (file attributes, API project lists, etc.) so the wizard offers a choice prompt instead of a free-text prompt. Adapters are invoked lazily and skipped under --no-prompt or the new --no-network flag; discovery failures degrade to a free-text prompt rather than aborting the wizard.

  • ✨ Added ubconnect github to-github: creates GitHub issues from selected needs (fnmatch patterns over need IDs) and patches the source RST in place to append the new issue numbers to :issue:.

  • ✨ Added ubconnect github sync-issue-refs: reconciles native GitHub sub-issues into the :issue: lists of the needs that own them, patching the source RST via the same atomic-write path.

  • ✨ Extended validate-issue-refs with three new report kinds: COVERAGE (needs missing :issue:), LIFECYCLE (all linked issues are closed but status is not in the configured done_status), and DRIFT (sub-issues exist on GitHub but not yet in :issue:). New flags --allow-coverage-gap and --sync plus the [ubconnect.validate_github_issues.lifecycle].done_status TOML option.

  • ✨ Added auto-injected weblink ReqIF attribute to SPEC-OBJECTS when weblink_pattern is configured.

  • ✨ Added --images-target-dir and --images-ref-dir flags to from-reqif for controlling where extracted images are written and how they are referenced from generated RST.

Fixes

  • 🐛 Fixed from-github not writing the :issue: field on imported needs, leaving validate-issue-refs unable to validate its own output. Imported needs now carry :issue: (the GitHub issue number), and the duplicate github_number extra has been dropped. This is a needs.json wire-format change: downstream Sphinx-Needs conf.py declarations and any scripts grepping the JSON must rename github_number to issue.

0.17.0

Released:

07.05.2026

New and Improved

  • ✨ Added GitHub Issues connector (from-github) for importing GitHub repository issues into Sphinx-Needs, plus validate-issue-refs to cross-check :issue: references on existing needs against the GitHub issue tracker. Supports label-driven need-type selection via type_mapping, fallback_type, and bullet_type. validate-issue-refs exits non-zero when no :issue: references are collected; pass --allow-empty to opt out. Authentication via GH_TOKEN or GITHUB_TOKEN environment variable. See GitHub Issues.

  • ✨ Added round-trip fidelity opt-ins for from-reqif and to-reqif to preserve SPEC-OBJECT-TYPE structure and SPEC-HIERARCHY across a round-trip. All keys default off; existing TOML configurations produce unchanged output.

Fixes

  • 🐛 Fixed to-reqif double-encoding XHTML content in attributes already declared XHTML-typed by the schema.

  • 🐛 Fixed from-reqif crashing on XHTML content containing HTML comments.

  • 🐛 Fixed from-reqif rejecting ReqIF files whose schema namespace is bound only via a prefix.

  • 🐛 Fixed from-reqif crashing on .reqifz archives whose ReqIF content carries no <SPECIFICATIONS> element.

  • 🐛 Fixed from-reqif mode = "per_section" rendering a blank line between nested heading titles and their underline when section names contain newlines.

  • 🐛 Fixed formatting in the error message for missing configuration sections.

0.16.0

Released:

22.04.2026

New and Improved

  • ✨ Added IBM DOORS Next Generation connector (from-doors-ng) for importing DNG artifacts into Sphinx-Needs via OSLC. Supports value_map with configurable on_unmapped_value behaviour. Credentials via TOML or env vars (DOORS_NG_HOST, DOORS_NG_USERNAME, DOORS_NG_PASSWORD). See IBM DOORS Next Generation (DNG).

  • 📚 Documentation is now versioned on GitHub Pages. /latest/ tracks main, tagged releases are published to /vX.Y.Z/, and /stable/ points to the latest release. A version switcher is available in the sidebar.

0.15.0

Released:

15.04.2026

New and Improved

  • ✨ Added ssl_verify option for Jama Connect (from-jama, to-jama, list-types, check). Disables SSL certificate verification for on-premises instances with self-signed certificates. Also available via --no-ssl-verify. See Basic Configuration and Basic Configuration.

Fixes

  • 🐛 Fixed from-reqif crashing on SPEC-RELATION-TYPE elements without a LONG-NAME attribute (spec-compliant per ReqIF XSD)

0.14.0

Released:

13.04.2026

New Features

  • ✨ Added value_map support to from-reqif mapping entries for automatic value translation during import. See Mapping with Value Translation.

  • ⚡ Improved to-reqif export performance by 48% for large datasets. Per-phase timing diagnostics are available via --verbose. See Performance Diagnostics.

Fixes

  • 🐛 Fixed from-reqif multi-value enum fields: all selected values are now collected and joined.

  • 🐛 Fixed from-reqif RST content sanitisation to avoid false-positive escaping of valid RST markup.

  • 🐛 Fixed from-reqif RST per_section mode: needs are grouped by root ancestor section with full nested heading hierarchy preserved; orphan needs go to _orphans.rst. See RST Per-Section Hierarchy.

Deprecations

0.13.0

Released:

27.03.2026

New and Improved

  • ✨ Added value_map to [ubconnect.to_reqif.mapping.*]. Provides explicit translation of Sphinx-Needs field values to ReqIF attribute values for enum and string datatypes. See Value Map (Explicit Value Translation).

0.12.0

Released:

16.03.2026

New and Improved

path_field can now also be used in Mode 0 (without type_value or container_as_need): the path is built from ancestor node titles in the ReqIF hierarchy tree. name_attribute can optionally override the attribute used for path segment names.

  • ✨ Added container_as_need and type_for_need to [ubconnect.from_reqif.section]. When container_as_need = true, section/container nodes are emitted as needs instead of being discarded, and their type is set to type_for_need. Two new operating modes are introduced:

    • Mode 1 (container_as_need only): structural nesting — any node with children becomes a container need regardless of spec-object type.

    • Mode 3 (container_as_need + type_value): typed container — nodes matched by type are emitted as container needs.

    Nodes that lack the configured mapping id attribute fall back to the ReqIF Spec-Object UUID (prefixed with id_prefix). ** BREAKING ** When no [ubconnect.from_reqif.section] configuration is provided, the legacy fallback has been removed. Mode 0 is the replacement and emits all nodes as flat needs instead of guessing section nodes based on the presence of children. See Operating Modes.

0.11.0

Released:

16.03.2026

New and Improved

  • 👌 Improved ReqIF-to-Needs section detection configuration (from-reqif) to support both spec-object-type and attribute-based discrimination. See Section Detection (Hierarchy).

  • ✨ Added path_field to [ubconnect.from_reqif.section] to populate a need field with the full section hierarchy path (for example "Root > SubFolder").

Fixes

  • 🐛 Fixed error handling when outpath is wrongly configured such as empty string

  • 🐛 Remove dependency on wmic for licensing on Windows

0.10.0

Released:

06.03.2026

New and Improved

0.9.0

Released:

27.02.2026

New and Improved

  • ✨ Added Jama Connector support Jama Connect

  • ✨ Added CSV Connector support CSV

  • ✨ Added support for 1:N mapping: a single ReqIF attribute can now be mapped to multiple Sphinx-Needs fields. See Mapping Configuration.

  • 👌 Improved validation for mapping field names, static field conflicts, and case-insensitive duplicates in ReqIF-to-Needs conversion.

Fixes

  • 🐛 Fixed error handling for mapping and static field configuration conflicts.

0.8.0

Released:

19.02.2026

New and Improved

  • ✨ Added support for template parameter in mapping configuration, enabling dynamic field rendering with MiniJinja.

  • ✨ Added pattern support for editlink and weblink fields.

  • ✨ Added optional import_date field to all needs exported to ReqIF, recording the UTC import timestamp.

  • ✨ Added alm_tool configuration option for to-reqif to specify target ALM tool (doors or codebeamer). See ALM Tool Configuration.

  • ✨ Added hierarchical section configuration support for to-reqif. See (see Section Configuration)

  • ✨ Added new options images_target_dir and images_ref_dir for from-reqif to handle ReqIFZ attachments (e.g., images)

  • 👌 Enhanced support for Sphinx-Needs 6 data types (integer, boolean, number, arrays) in ReqIF conversion

Fixes

  • 🐛 Fixed ReqIF XML identifier generation to comply with XSD ID schema requirements

0.7.2

Released:

27.01.2026

New and Improved

  • 👌 Improved error message for the license configuration

Fixes

  • 🐛 Fixed relative license file path resolution using wrong app_id

  • 🐛 Supported ReqIF Datatype BOOLEAN, INTEGER, REAL, and DATE for from-reqif

0.7.1

Released:

26.01.2026

Fixes

  • 🐛 update the dependency of ReqIF to 0.0.48.

0.7.0

Released:

04.12.2025

New and Improved

  • ✨ Added origin_field option for to-reqif and from-reqif

  • 👌 Changed id_prefix behavior for from-reqif (avoid double-prefix; preserve Sphinx-Needs IDs)

0.6.0

Released:

20.11.2025

New and Improved

  • ✨ Added uuid_source for to-reqif and uuid_target for from-reqif

  • 👌 Do not force the ID prefix _ for from-reqif

  • 👌 Updated default mapping attribute names for to-reqif (prefer need_*)

  • 👌 Improved warnings for missing fields in to-reqif mapping configuration

  • 👌 Aligned outpath extension with reqifz flag

  • 👌 Improved warning for invalid ReqIF attribute names in from-reqif

  • 👌 Improved warning for missing mapped ReqIF attributes in from-reqif

Fixes

  • 🐛 Fixed the default datatype string not being applied when not given in the mapping configuration for to-reqif

0.5.0

Released:

30.10.2025

New and Improved

  • ✨ Added --config option for to-reqif and from-reqif

  • ✨ Added configuration for custom mappings from Sphinx-Needs fields to ReqIF attributes

0.4.0

Released:

16.10.2025

New and Improved

  • ✨ Added conversion from ReqIF SpecRelation to Sphinx-Needs link fields (from-reqif)

Fixes

  • 🐛 Fixed duplicate identifiers of SPEC-OBJECT and SPEC-HIERARCHY in the ReqIF XML file when using to-reqif

0.3.1

Released:

02.10.2025

Fixes

  • 🐛 Fixed section hierarchy when using to-reqif

  • 🐛 Fixed missing dependency error when using from-reqif

0.3.0

Released:

18.09.2025

New and Improved

  • ✨ Added CLI command from-reqif

0.2.0

Released:

25.08.2025

New and Improved

  • ✨ Added CLI option name

  • ✨ Added CLI option group-types

  • ✨ Export the name of how need items are grouped into ReqIfSpecifications to reqIf.Prefix

  • ✨ Resolve section hierarchy of need items and convert them to ReqIFSpecHierarchy

0.1.2

Released:

09.07.2025

Fixes

  • 🐛 Fixed need title to ReqIF.Name

  • 🐛 Fixed need content to ReqIF.Text

0.1.1

Released:

03.07.2025

New and Improved

  • Significantly reduced the binary package size of ubConnect.

Fixes

  • 🐛 Fixed enum serialization in reqif

0.1.0

Released:

18.06.2025

Initial release of the ubConnect CLI.

This version features exporting ReqIF files from needs.json.