YAML files with directives

[adam-moss]

This is probably more a stylistic thing but if you have a yaml file

%YAML 1.2
# yaml-language-server: $schema=https://json.schemastore.org/pre-commit-config.json
---
default_install_hook_types:
  - pre-commit
...

and update it with copywrite headers you end up with

# Copyright (c) HashiCorp, Inc.
# SPDX-License-Identifier: MPL-2.0

%YAML 1.2
# yaml-language-server: $schema=https://json.schemastore.org/pre-commit-config.json
---
default_install_hook_types:
  - pre-commit
...

This contrasts with the behaviour of shell scripts which maintain the shebang as the first line.

I don't think it particularly matters for TAG directives but in the case of the YAML directive should this be handled similarly?

[CalebAlbers]

Hmm, this is an interesting one, and I get the stylistic desire. The part of the code that handles language headers can be found here, and historically has only been used in places where the language itself requires the directive/header to be at the very top of the file.

In your experience, do you see situations where %YAML directives are accompanied by comments? e.g.:

# This file needs 1.2 because...
%YAML 1.2

or this (taken from the YAML spec example)

%YAML 1.3 # Attempt parsing 
          # with a warning
---
"foo"

I admittedly haven't done much with YAML directives, so I'm not sure what is common there. I see the Linux project and a few others put SPDX IDs before the directive based on this GitHub Code Search, but I'm not against the idea.

[adam-moss]

Looking at a similar search with sourcegraph I see almost no comments on or preceding the %YAML directive.

Some eclipse repos have the full license text in them, e.g. this site.yaml, and some nvidia ones like this, do the same but using a copyright SPDX header.

I don't think there is a right or wrong way here, but my preference would be that if the %YAML 1.2 header is present it remained at the top of the file.