@stof Adding the useAttributeAsKey would allow us to set specific metadata by key when using the config builder.
But we'd lose out on the ability to set all metadata in 1 call if we already created an instance of the parent node builder.

This is due to the generated config changing from

    /**
     * @param ParamConfigurator|list<ParamConfigurator|mixed> $value
     *
     * @return $this
     */
    public function metadata(ParamConfigurator|array $value): static
    {
        $this->_usedProperties['metadata'] = true;
        $this->metadata = $value;
    
        return $this;
    }

To

    /**
     * @return $this
     */
    public function metadata(string $key, mixed $value): static
    {
        $this->_usedProperties['metadata'] = true;
        $this->metadata[$key] = $value;

        return $this;
    }

Would a breaking change like this be a problem for a bugfix? (cc @nicolas-grekas )

As a sidenote, a update to the workflow docs would also be required in the case we would want to perform these changes.
As it shows some examples for the php configs setting the metadata as an array. And we would lose this option.

    $pullRequest->place()
        ->name('review')
        ->metadata(['description' => 'Human review']);
    $pullRequest->place()->name('merged');
    $pullRequest->place()
        ->name('closed')
        ->metadata(['bg_color' => 'DeepSkyBlue',]);

The XML config in general seems to be broken when parsing though. The example showed on the doc page shows nodes, that should actually be attributes.

But having a combination of place nodes, with and without metadata seems to actually break when using XML config, due to the callbacks used in the beforeNormalization possibly not accounting properly for the differences in data structure of the passed $places var, depending on the type of config used :(

Small example of the data contained in the $places argument of the normalization callback, when using the example configs from the docs:

PHP
^ array:6 [
  0 => array:1 [
    "name" => "start"
  ]
  1 => array:1 [
    "name" => "coding"
  ]
  2 => array:1 [
    "name" => "test"
  ]
  3 => array:2 [
    "name" => "review"
    "metadata" => array:1 [
      "description" => "Human review"
    ]
  ]
  4 => array:1 [
    "name" => "merged"
  ]
  5 => array:2 [
    "name" => "closed"
    "metadata" => array:1 [
      "bg_color" => "DeepSkyBlue"
    ]
  ]
]
^ array:6 [
 
YAML
^ array:6 [
  "start" => null
  "coding" => null
  "test" => null
  "review" => array:1 [
    "metadata" => array:1 [
      "description" => "Human review"
    ]
  ]
  "merged" => null
  "closed" => array:1 [
    "metadata" => array:1 [
      "bg_color" => "DeepSkyBlue"
    ]
  ]
]
 
# XML
^ array:6 [
  0 => "start"
  1 => "coding"
  2 => "test"
  3 => array:2 [
    "name" => "review"
    "metadata" => array:2 [
      "description" => "Human review"
      "other_value" => "Some other value"
    ]
  ]
  4 => "merged"
  5 => array:2 [
    "name" => "closed"
    "metadata" => array:1 [
      "bg_color" => "DeepSkyBlue"
    ]
  ]
]

Would a breaking change like this be a problem for a bugfix? (cc @nicolas-grekas )

it would yes, since that'd break existing configs

Mhm, that does create an issue then tbh. As i'm not really sure how to fix the return type, if we cannot add the useAttributeAsKey, seeing how the normalizeKeys was not a preferable way to detect the difference.

Adding a new option we could set to indicate a list or array kinda feels like a bandaid fix, tiptoeing around the problem that the config might just be incorrectly defined to begin with.

I also don't see a clear way to mark methods generated by the builder as deprecated. So we could replace it in the next major. Atleast not without deprecating the entire node, which i don't want, as we still want the node, but differently configured :/