Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Standard YAML in template files #439

Open
tkphd opened this issue Apr 12, 2023 · 0 comments
Open

Standard YAML in template files #439

tkphd opened this issue Apr 12, 2023 · 0 comments

Comments

@tkphd
Copy link

tkphd commented Apr 12, 2023

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant