✨ Add default and predicates keys to needs_fields and needs_extra_links, deprecates needs_global_options

[chrisjsewell]

This PR deprecates needs_global_options in favor of adding default and predicates keys directly to needs_fields and needs_extra_links.
This consolidation follows on from #1611, to simplify field schema configuration and enables the possibility for future composability, such as per-need-type sub-schemas.

Key changes:

• Adds default and predicates keys to needs_fields and needs_extra_links configuration options
• Deprecates needs_global_options with a migration path
• Updates documentation to reflect the new configuration approach

As per the new test, here is an example of moving from needs_global_options to the new default configuration keys:

OLD:

needs_fields = {
    "option_1": {},
    "option_2": {},
    "option_3": {},
    "option_4": {},
    "option_5": {},
}

needs_extra_links = [
    {
        "option": "link1",
    },
    {
        "option": "link2",
    },
]

needs_global_options = {
    "tags": {
        "predicates": [
            ('status == "implemented"', ["a", "b"]),
            ('status == "closed"', ["c", "[[copy('status')]]"]),
        ],
        "default": ["d"],
    },
    "collapse": {"default": True},
    "hide": {"default": False},
    "layout": {"default": "clean_l"},
    "option_1": {"default": "test_global"},
    "option_2": {"default": "[[copy('id')]]"},
    "option_3": {"predicates": [('status == "implemented"', "STATUS_IMPL")]},
    "option_4": {
        "default": "STATUS_UNKNOWN",
        "predicates": [('status == "closed"', "STATUS_CLOSED")],
    },
    "option_5": {
        "predicates": [
            ('status == "implemented"', "STATUS_IMPL"),
            ('status == "closed"', "STATUS_CLOSED"),
        ],
        "default": "final",
    },
    "link1": {"default": ["SPEC_1"]},
    "link2": {
        "predicates": [
            ('status == "implemented"', ["SPEC_2", "[[copy('link1')]]"]),
            ('status == "closed"', ["SPEC_3"]),
        ],
        "default": ["SPEC_1"],
    },
}

NEW:

needs_fields = {
    "tags": {
        "predicates": [
            ('status == "implemented"', ["a", "b"]),
            ('status == "closed"', ["c", "[[copy('status')]]"]),
        ],
        "default": ["d"],
    },
    "collapse": {"default": True},
    "hide": {"default": False},
    "layout": {"default": "clean_l"},
    "option_1": {"default": "test_global"},
    "option_2": {"default": "[[copy('id')]]"},
    "option_3": {"predicates": [('status == "implemented"', "STATUS_IMPL")]},
    "option_4": {
        "default": "STATUS_UNKNOWN",
        "predicates": [('status == "closed"', "STATUS_CLOSED")],
    },
    "option_5": {
        "predicates": [
            ('status == "implemented"', "STATUS_IMPL"),
            ('status == "closed"', "STATUS_CLOSED"),
        ],
        "default": "final",
    },
}

needs_extra_links = [
    {
        "option": "link1",
        "default": ["SPEC_1"],
    },
    {
        "option": "link2",
        "predicates": [
            ('status == "implemented"', ["SPEC_2", "[[copy('link1')]]"]),
            ('status == "closed"', ["SPEC_3"]),
        ],
        "default": ["SPEC_1"],
    },
]

[Copilot]

Pull request overview

This PR deprecates needs_global_options in favor of adding default and predicates keys directly to needs_fields and needs_extra_links. This consolidation simplifies field schema configuration and enables future composability, such as per-need-type sub-schemas.

Key changes:

• Adds default and predicates keys to needs_fields and needs_extra_links configuration options
• Deprecates needs_global_options with a migration path
• Updates documentation to reflect the new configuration approach

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_global_options.py	Removed (replaced by test_field_defaults.py)
tests/test_field_defaults.py	New comprehensive test file for field and link defaults
tests/doc_test/doc_field_defaults/index.rst	New test fixture for field defaults validation
tests/doc_test/doc_field_defaults/conf.py	Test configuration demonstrating new field/link default syntax
tests/snapshots/test_field_defaults.ambr	Snapshot data for field defaults tests
sphinx_needs/needs.py	Core logic changes to support defaults in fields/links and deprecate global_options
sphinx_needs/data.py	Updated docstring to remove reference to needs_global_options
sphinx_needs/config.py	Added default and predicates keys to LinkOptionsType and NeedFields types
docs/tutorial.rst	Updated to reference needs_extra_links instead of needs_global_options
docs/schema/index.rst	Updated to reference field/link defaults instead of needs_global_options
docs/dynamic_functions.rst	Removed needs_global_options from list of supported options
docs/directives/needextend.rst	Updated reference from needs_global_options to needs_fields
docs/directives/need.rst	Removed example using needs_global_options
docs/configuration.rst	Major restructure: moved needs_global_options to deprecated section and added default configuration to fields/links sections

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 95.45455% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 88.22%. Comparing base (4e10030) to head (f54c3eb).
⚠️ Report is 220 commits behind head on master.

Files with missing lines	Patch %	Lines
sphinx_needs/needs.py	94.11%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1612      +/-   ##
==========================================
+ Coverage   86.87%   88.22%   +1.34%     
==========================================
  Files          56       70      +14     
  Lines        6532     9907    +3375     
==========================================
+ Hits         5675     8740    +3065     
- Misses        857     1167     +310     

Flag	Coverage Δ
pytests	88.22% <95.45%> (+1.34%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ubmarco]

We are losing out on the description after the deprecation. Was this used for anything?
That could also be part of the schema description, if that's the case.

[chrisjsewell]

No it wasn't used for anything in particular.
It's always nice to be able to document enum variants (as would be the rust terminology) but how can you do this in the schema? You could use oneOf + const, but that gets messy to "analyse"

{
  "type": "string",
  "oneOf": [
    {
      "const": "draft",
      "description": "Work in progress; not yet reviewed"
    },
    {
      "const": "approved",
      "description": "Reviewed and approved for use"
    },
    {
      "const": "rejected",
      "description": "Reviewed and explicitly rejected"
    }
  ]
}