From 1b427664f5b716c431f26a7d9d214f14ccbc4dd7 Mon Sep 17 00:00:00 2001 From: brandon s allbery kf8nh Date: Thu, 26 Sep 2024 18:55:40 -0400 Subject: [PATCH] update changelog.d format and Matrix link `changelog-d` was changed to make `packages` a list, so reflect this in the example. Also remove the "omit if it's an overarching change" part: we must list all packages if we want it to show up when generating release changelogs. While I was there, I updated the Matrix channel reference because it was still reflecting the EMS Libera bridge. --- CONTRIBUTING.md | 23 +++++++++++++++++++++-- 1 file changed, 21 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2049b978528..094d291362b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -345,13 +345,32 @@ 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. + +```markdown +--- +synopsis: Add feature xyz +packages: [cabal-install] +prs: #0000 +issues: #0000 #0000 +significance: significant +--- + +- Detail number 1 +- Detail number 2 + +``` +The package list must be enclosed in square brackets, but they aren't needed for `prs` or `issues`. + Only the `synopsis` and `prs` fields are required, but you should also set the others where applicable. | Field | Description | | ----- | ----------- | | `synopsis` | Brief description of the change. Often just the pr title. | | `description` | Longer description, with a list of sub-changes. Not needed for small/atomic changes. | -| `packages` | Packages affected by the change (`cabal-install`, `Cabal`...). Omit if it's an overarching or non-package change. | +| `packages` | Packages affected by the change (`cabal-install`, `Cabal`...). Omit if it's a non-package change. | | `prs` | Space-separated hash-prefixed pull request numbers containing the change (usually just one). | | `issues` | Space-separated hash-prefixed issue numbers that the change fixes/closes/affects. | | `significance` | Set to `significant` if the change is significant, that is if it warrants being put near the top of the changelog. | @@ -377,7 +396,7 @@ There are a few main venues of communication: * Many developers idle on `#hackage` on [`irc.libera.chat`](https://libera.chat). The `#ghc` channel is also a decently good bet. * You can join the channel using a web client, even anonymously: https://web.libera.chat/#hackage - * Alternatively you can join it using [matrix](https://matrix.org/): https://matrix.to/#/#hackage:libera.chat + * Alternatively you can join it using [matrix](https://matrix.org/): https://matrix.to/#/#hackage:matrix.org Releases --------