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 <[email protected]> --------- Co-authored-by: Artem Pelenitsyn <[email protected]> Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>
haskell · Sep 30, 2024 · d215dc3 · d215dc3
1 parent 6d25218
commit d215dc3
Showing 1 changed file with 21 additions and 2 deletions.
diff --git 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