Standard YAML in template files

[tkphd]

Actionable suggestion

Insert a description of the file followed by --- at the start of every YAML template-file, so that downstream repositories are created with self-documenting standards-compliant YAML in regular and workflow files.

Remapped from carpentries/workbench-template-md#24 (comment)

Background

The generated workbench template provides a config.yaml and various .github YAML files that do not begin with ---. This is at odds with the YAML Standard and gets flagged as an error by YAML Lint.

@zkamvar pointed out that there is vigorous discussion in the YAML community over the subject. In particular, the YAML Spec community has an open issue on appropriateness of --- in machine-generated vs. human-written YAML, and/or data serialization vs. config file usage. Apparently, The Carpentries' glosario tool tired of the debate, and has disabled the check for --- at the beginning of YAML documents.

Rationale

It makes no difference to a human reader if a YAML document starts with --- or not. For data serialization, where a single file may contain multiple YAML documents, the --- delimiter between documents is important, but this is almost never the use case for The Carpentries.

However, this feature of the YAML standard can be very helpful in documenting the YAML file. Currently, config.yaml starts out

#------------------------------------------------------------
# Values for this lesson.
#------------------------------------------------------------

# Which carpentry is this (swc, dc, lc, or cp)?

It takes a second to figure out whether that first heading applies to the immediately following block, the whole file, or some subset of settings. In addition, as a heading, it is necessarily terse.

Using the document-start syntax, it is possible to describe the document using full sentences, then delineate where the top-level description ends and the details begin with ---:

# Configuration and template parameters for your lesson.
# Values modified here will propagate through the website
# when you build it, setting the appropriate logo/theme,
# contact info, and episode structure.
---
title: {{ title }}  # appears at the top of every page

# Which carpentry is this? Choose one of:
...

Benefits

Making this change would improve the workbench lessons' documentation, and would help our YAML files pass syntax/linting tools like yamllint with default settings and without throwing errors.

Potential Problems

Unknown. All machine readers will parse single-document YAML files correctly, whether --- is present or not. Human readers can reasonably be expected to wonder what on earth the --- means, and why it's present, and maybe even delete it.

Alternative

Instead of updating our YAML files, we could ship the workbench template with a top-level .yamllint.yml that disables checking for --- at the beginning of each document. This would eliminate confusion in human readers of YAML files containing a single document.