Changelog

0.19.0

Released:

11.08.2026

Breaking

  • 💥 from-csv now honours an explicit id_prefix = "" instead of silently falling back to the CSV_ default. Configurations that set it — in TOML or via --id-prefix "" — produce need IDs without the prefix (REQ001 rather than CSV_REQ001), so references to the previously prefixed IDs in downstream documents must be updated. Omitting the key still yields CSV_.

  • 💥 [ubconnect.to_csv] no longer accepts outdir; a configuration carrying it now fails with a Pydantic extra-forbidden validation error. The key was inherited but never used — to-csv writes to outpath — so removing it from the section is the whole migration. Connectors that write into a directory are unaffected.

New and Improved

  • ✨ Added the Jira write direction: ubconnect jira to-jira creates one Jira issue per selected need, and ubconnect jira refresh-status reads the current Jira status of every created issue back into a needs.json. A MiniJinja issue template renders need fields and the fields of needs linked to it into the issue summary, description, and text-shaped custom fields; every created issue carries a back-link to the exported need as a Jira remote link. Needs are selected with a filter expression over need fields, and --dry-run prints the rendered payload without contacting Jira. Content flows one way — only the issue status is read back. See Creating Jira issues from needs.

  • ✨ to-jira records the need-to-issue mapping in a state file and can rebuild it from Jira when that file is lost, so a pipeline that keeps no state between runs still creates no duplicate issues. Set need_field to have the need reference written into a dedicated Jira field, and reconcile = "always" (or --reconcile) to query Jira before every export. See Creating Jira issues from needs.

  • ✨ The CSV connector supports mapping multiple named link relations in both directions via [ubconnect.from_csv.links] and [ubconnect.to_csv.links] (with optional per-column link_delimiters). The legacy links_column keeps working as a shorthand. On export the links table maps each listed relation to its header; the default links / links_back columns and back-link (<relation>_back) fields are dropped unless listed explicitly, and include_links is the master switch for the link columns ubConnect recognises. A link header that collides with a generic field carried in the needs.json is rejected during export instead of silently overwriting a value; a forward relation absent from the table is emitted as a generic column (joined with ', ', unaffected by include_links). See CSV.

Fixes

  • 🐛 Fixed the Jira connector failing against Jira Cloud with Malformed Jira search response: missing 'issues' or 'total' key. Atlassian removed the offset-based /rest/api/2/search endpoint; its replacement paginates by nextPageToken and returns no total. This broke every JQL search, so from-jira could import nothing and to-jira could not rebuild its mapping — which, with reconciliation unavailable, meant a lost state file produced duplicate issues. Pagination now follows either contract, so Jira Server and Data Center are unaffected.

  • 🐛 Fixed to-jira --dry-run hiding needs that were skipped or that failed to render, so a broken template previewed as 0 need(s) would be exported. The preview now reports every selected need and exits non-zero when one fails to render.

  • 🐛 Fixed on_error = "fail" surfacing a raw traceback instead of an error message when an issue template could not be rendered.

  • 🐛 Fixed per-need failure reasons restating the entire Jira HTTP response — every header plus the raw body — which buried the actual cause. Failures now report as HTTP 400: Specify a valid issue type.

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.