Document `fieldpath` semantics

[Mitsuwa]

What happened?

Setting an annotation or label via SetValue using a label or annotation key with a "." is set incorrectly ie: prometheus.io.metrics

It will be set as

metadata:
  labels:
    prometheus:
      io:
        metrics: /metrics

It should result in

metadata:
  labels:
    prometheus.io.metrics: /metrics

This seems to be more of an issue with the SetValue in fieldpath Pave objects.

I understand that you can use SetAnnotations or SetLabels but this requires either merging the existing annotations together, which would often take longer than setting the fields individually, or requires knowing the full annotations or labels at the start. either way it would be nice to use SetValue this way as well. If it is not intended to be used this way, perhaps a comment suggesting alternatives would be good

How can we reproduce it?

using this composed_test file

package composed

import (
	"fmt"
	"testing"

	"sigs.k8s.io/yaml"
)

func TestSetValue(t *testing.T) {
	cd := New()
	cd.SetAPIVersion("example.org/v1")
	cd.SetKind("CoolComposedResource")

	cd.SetValue("metadata.labels.prometheus.io.metrics", "/metrics")
	cd.SetValue("metadata.labels.\"prometheus.io.url\"", "https://exampleprom.io")
	cd.SetValue("metadata.annotations.prometheus.io.metrics", "/metrics")
	cd.SetValue("metadata.annotations.\"prometheus.io.url\"", "https://exampleprom.io")

	y, _ := yaml.Marshal(cd)

	fmt.Println(string(y))
}

you will see the following output

$ go test -v ./...
=== RUN   TestSetValue
apiVersion: example.org/v1
kind: CoolComposedResource
metadata:
  annotations:
    prometheus:
      io:
        metrics: /metrics
        url: https://exampleprom.io
  labels:
    prometheus:
      io:
        metrics: /metrics
        url: https://exampleprom.io

--- PASS: TestSetValue (0.00s)
PASS
ok  	github.com/crossplane/function-sdk-go/resource/composed	0.226s

What environment did it happen in?

Crossplane version: Latest version