yaml include for upsun projects

[gilzow]

Where on docs.platform.sh should be changed?

https://docs.upsun.com/learn/overview/yaml/yaml-structure.html

What exactly should be updated?

Make a (or add to the existing) note that if you use yaml !includes in your main upsun config file, they need to be either stored in a different directory (or subdirectory of .upsun) and/or use a different file extension other than *.yaml.

Additional context

In Upsun, we glob all files located directly under the .upsun/ directory regardless of their names, and merge them into one single structure. In Platform we do not do this so including a yaml file (stored potentially in ./.platform) in your main .platform.app.yaml file is perfectly fine. In Upsun however, this will throw an error.

Example:
"main" upsun config file (e.g. config.yaml)

applications:
  my_project:
    hooks:
      build: !include
        type: string
        path: hooks.build.yaml

where hooks.build.yaml is also stored in .upsun will produce an error Contents should be a YAML map.

Instead, hooks.build.yaml should either be moved into a different directory (or a descendent/sub directory of .upsun) OR have its file extension changed to something other than .yaml.