♻️ Change needs_global_options format

[chrisjsewell]

In the current format each key value can be in multiple different formats, which makes it difficult to understand, parse, validate, and provide a JSON schema for in ubproject.toml

In this PR we deprecate the old format (it can still be used for now but will emit a warning with the new format),
and replace it with a slightly more verbose, but consistent format:

old:

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"),
    ],
}

new:

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",
    },
}

new, in ubproject.toml format:

[needs.global_options]
field1.default = "a"
field2.predicates = [['status == "done"', "a"]]
field3.predicates = [['status == "done"', "a"]]
field3.default = "b"
field4.predicates = [
    ['status == "done"', "a"],
    ['status == "ongoing"', "b"],
    ['status == "other"', "c"]
]
field4.default = "d"

and this is the auto-generated JSON schema from ubcode:

{
  "properties": {
        "global_options": {
          "additionalProperties": {
            "$ref": "#/definitions/GlobalOptionValue"
          },
          "default": {},
          "description": "Default values given to specified fields of needs",
          "type": "object"
        }
  },
  "definitions": {
    "GlobalOptionValue": {
      "properties": {
        "default": {
          "default": null,
          "description": "This value is used, if the field has not been specifically set, and no predicate matches."
        },
        "predicates": {
          "default": [],
          "description": "A list of (filter predicate, value) to match against the need. If the field has not been specifically set, the value of the first predicate that matches is used.",
          "items": {
            "items": [
              {
                "type": "string"
              },
              true
            ],
            "maxItems": 2,
            "minItems": 2,
            "type": "array"
          },
          "type": "array"
        }
      },
      "type": "object"
    }
  }
}

[codecov]

Codecov Report

Attention: Patch coverage is 95.65217% with 1 line in your changes missing coverage. Please review.

Project coverage is 88.54%. Comparing base (4e10030) to head (da23e38).
Report is 118 commits behind head on master.

Files with missing lines	Patch %	Lines
sphinx_needs/needs.py	95.23%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1413      +/-   ##
==========================================
+ Coverage   86.87%   88.54%   +1.66%     
==========================================
  Files          56       60       +4     
  Lines        6532     7231     +699     
==========================================
+ Hits         5675     6403     +728     
+ Misses        857      828      -29     

Flag	Coverage Δ
pytests	88.54% <95.65%> (+1.66%)	⬆️

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]

Explicit is better than implicit. Thanks & approved.