From ba1b29ae4a978707aeb1f7e9ab8dff35d4526075 Mon Sep 17 00:00:00 2001 From: brandon s allbery kf8nh Date: Tue, 1 Oct 2024 16:15:47 -0400 Subject: [PATCH] patchups to `changelog.d` file descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bug copied from `changelog-d`'s `README.md`. A good example of why copying it into `CONTRIBUTING.md` because we can't reference it from there is a bad idea. ☹ --- CONTRIBUTING.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18a4d64c5bd..93835320bb2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -350,14 +350,15 @@ description: { Changelogs may also be written in "markdown-frontmatter" format. This is useful if your description contains braces, which must be escaped with backslashes in `.cabal` file -format. +format. The front matter is in YAML syntax, not `.cabal` file syntax, and the file +_must_ begin with a line containing only hyphens. ```markdown --- synopsis: Add feature xyz packages: [cabal-install] -prs: #0000 -issues: #0000 #0000 +prs: 0000 +issues: [0000, 0000] significance: significant --- @@ -365,7 +366,11 @@ significance: significant - Detail number 2 ``` -The package list must be enclosed in square brackets and comma-separated, but this isn't needed for `prs` or `issues`. +The package list must be enclosed in square brackets and comma-separated, but this +isn't needed for `prs` or `issues`; those are free-form and any YAML syntax will +be accepted. Note that the number signs on PR and issue numbers are required in +`.cabal` file syntax, but won't work in markdown-frontmatter syntax because they +signify comments in YAML. Only the `synopsis` and `prs` fields are required, but you should also set the others where applicable.