From d215dc37778d1f35f4931762b896acdc30e56405 Mon Sep 17 00:00:00 2001
From: brandon s allbery kf8nh <allbery.b@gmail.com>
Date: Mon, 30 Sep 2024 17:10:25 -0400
Subject: [PATCH] update changelog.d format and Matrix link (#10383)
* 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.
* Update CONTRIBUTING.md
Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
---------
Co-authored-by: Artem Pelenitsyn <a.pelenitsyn@gmail.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
---
CONTRIBUTING.md | 23 +++++++++++++++++++++--
1 file changed, 21 insertions(+), 2 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b2d7cc47ff..18a4d64c5b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -348,13 +348,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 and comma-separated, but this isn'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. |
@@ -379,7 +398,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
--
GitLab