0.24.x

0.24.1

Released:

04.03.2026

✨ New Features

• Config override support in the VS Code extension

  The VS Code extension now exposes two new settings, ubcode.server.configOverride and ubcode.mcp.configOverride, that let you override any ubproject.toml value directly from your editor settings without modifying the project file.

  Each setting accepts a JSON object whose keys and values mirror the TOML configuration. The overrides are serialized to TOML and passed to the language server (via a -c CLI flag) and the MCP server (via the UBCODE_CONFIG_OVERRIDE environment variable), respectively.

  A prime use case is controlling variant resolution (added in 0.24.0) on the fly. For example, to change the active build_tags without editing ubproject.toml:

  {
    "ubcode.server.configOverride": {
      "build_tags": ["html", "draft"]
    }
  }
  

  This makes it easy to switch between build variants while developing, and to preview how different tag combinations affect your requirements. Changes to either setting take effect immediately: the language server restarts and the MCP server definition is refreshed automatically.

0.24.0

Released:

03.03.2026

✨ New Features

• Variant resolution for needs

  Need fields and links can now contain variant functions using the <<...>> syntax, allowing conditional values that resolve based on configured variants and filter data. This implements the Sphinx-Needs variant functions feature, bringing ubCode closer to full feature parity with sphinx-needs. See Supported toolchain for the full list of supported configurations, and Variants for configuration details.

  Three expression forms are supported:

  • Named variants (<<name: value_if_match, fallback>>): name is looked up in the [needs.variants] configuration mapping.

  • Bracketed expressions (<<[expr]: value_if_match, fallback>>): expr is evaluated directly as a filter expression.

  • Fallback values: the last comma-separated value is used when no expression matches.

  For example:

  .. req:: My requirement
     :id: REQ_001
     :status: <<is_open: active, inactive>>
  

  Variant resolution runs after needextend processing, so extended field values are available to variant expressions. Resolved values are fully validated downstream. Parse and evaluation errors are surfaced as needs.variant diagnostics.

  Variant syntax is only parsed for fields that opt in: either by setting parse_variants = true in the field’s needs.fields schema (sphinx-needs v7+), or by listing the field name in variant_options.

  Incremental builds only re-resolve needs that have changed, and a pre-parsed expression cache avoids redundant work during parallel resolution.

• build_tags configuration attribute

  A new build_tags list can be set in ubproject.toml to declare the active build tags for a project. This replicates the Sphinx tags feature, making the same set of tags available to variant filter expressions as a list variable and enabling build-target-conditional field values.

  For example, given the configuration:

  build_tags = ["html"]
  
  [needs.variants]
  is_html = "'html' in build_tags"
  

  a need with :status: <<is_html: web_only, general>> will resolve to web_only when html is in build_tags, or general otherwise.

  Tags can also be overridden from the CLI using the -c option, without modifying ubproject.toml:

  ubc build index -c "build_tags = ['html', 'draft']"
  

  or via the UBCODE_CONFIG_OVERRIDE environment variable.

  See Top-level options for full documentation.