From 8e03411c4f093a0f976745eb16d23c503bb055f6 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Mon, 6 Jan 2025 18:26:07 -0500
Subject: [PATCH 01/20] release-management: initial commit

---
 release-management.mkd | 274 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 274 insertions(+)
 create mode 100644 release-management.mkd

diff --git a/release-management.mkd b/release-management.mkd
new file mode 100644
index 0000000..fb299c3
--- /dev/null
+++ b/release-management.mkd
@@ -0,0 +1,274 @@
+---
+title: GHC Release Management
+authors:
+ - Simon Peyton Jones
+ - Ben Gamari
+ - Andreas Klebinger
+ - Julian Ospald
+---
+
+These notes summarise a discussion to improve GHC's release processes,
+especially concerning the partnership between
+
+* "upstream producers": those producing GHC's releases (roughly: the GHC team), and
+* "downstream consumers": those consuming them (roughly: ghcup, library authors, Stack team, Stackage, Linux distros including Nix, HLS, Cabal, Core Libraries Committee).
+
+This document is a work in progress. 
+
+In order to understand where we can improve it is important
+to understand the areas where our downstream users struggle. We have started to
+collect some such reports from downstream stakeholders in [this
+document][pain-points]. Others are invited to add to this list.
+
+[pain-points]: https://docs.google.com/document/d/1JYYciVcSj34YyC07i_qnQyJ8PHXsA7VzdC2BC_cXB1k
+
+
+# 1. Motivation
+
+GHC is a complex artefact, so it is all too easy for upstream producers to
+produce releases that somehow fail to meet the expectations of downstream
+consumers. These mis-matched expectations can cause friction and aggravation,
+as well as extra work (sometimes a lot of it).
+
+Some of this is just hard: There is a lot to do across many facets of a complex
+project. However, the aim of this document
+is to avoid unnecessary friction, by promoting clarity, accurate and timely
+communication, and explicitly-articulated expectations.
+
+More specifically, we propose two significant changes:
+
+1. **Explicitly articulate a list of expectations (or invariants) about
+   releases**, things that upstream producers undertake to maintain, and on
+   which downstream consumers can rely.   See Section 3.  
+
+2. **Define a communications plan** that describes how the upstream team will
+   communicate with downstream consumers.  See Section 4.
+
+
+# 2. Expectations/invariants for GHC releases
+
+The goal of this section to is lay forth a set of technical invariants
+regarding GHC's distribution practices which downstream users can rely upon;
+the general aim of this is to ensure that GHC build products are fit for
+consumption without modification or augmentation by downstream distributors.
+
+Here we seek to precisely articulate these expectations.
+GHC (e.g. packagers and end-users) can rely upon. These are offered as ideals
+to which both distributors and GHC developers both aspire. We recognize that
+not all of these ideals have been realized: while some we can guarantee today,
+others may be desireable but are not yet attainable. We will mark the latter with
+a [🔴] to indicate that help could be used in these areas.
+
+Regardless, by specifying these goals in concrete terms we hope to better prioritize
+work on GHC to improve the downstream experience. Moreover, this list can serve
+as a concrete list of items which can be tested in GHC and its release process,
+making these guarantees robust.
+
+In various places we will refer to the [GHCup][GHCup] distribution channel due
+to its wide adoption and close involvement with GHC upstream.
+
+[GHCup]: https://www.haskell.org/GHCup/
+
+
+## 2.1. Release artifacts
+
+* GHC will clearly document which platforms releases support according to the establish [platform tier classification][platform-tiers]
+* Starting from a source distribution tarball, on all tier 1 platforms:  
+  * GHC itself, including all of its boot libraries, must build to produce a functional compiler  
+  * The user’s guide and Haddock documentation for GHC and boot libraries must build  
+  * No such guarantees are provided for Tier 2 or lower platforms  
+* Haddock documentation for GHC-maintained packages (e.g. `base`, `template-haskell`, the `ghc` library, `ghc-internal`, `ghc-prim`) is available on Hackage from day 0 and is fully functional.  
+* Bindists consistently include a minimum set of expected features. Specifically:  
+  * the compiler, `iserv`, `ghci`, `haddock`, `unlit`
+  * corresponding manual pages on platforms where these are supported
+  * HTML users guide
+  * Haddocks  
+  * profiling and vanilla libraries  
+  * Hadrian bootstrap sources for the latest minor GHC releases of the last three major release series
+
+  Note that certain characteristics of bindists are inherently different
+  between platforms (e.g. static vs dynamic linkage, `libffi`, `gmp`, `libc`
+  versions, etc). These attributes are not covered in the above.
+* The `-testsuite` distribution tarball should be tested regularly (e.g. via the nightly validation pipeline) via CI [🔴]
+* Binary distributions should provide a stable interface for configuration and installation (`configure`, `make`, `hadrian`)  
+  * For this to happen one needs to define the desired feature set [🔴], after which tests can be added to ensure it is maintained.  
+  * The same is true for building from source. This requires hadrian features to be split into “stable” user facing and development workflow features [🔴]
+* Ensure testsuite distribution passes across all supported platforms and configurations.
+
+The GHC and GHCup teams will take an active role in providing releases via GHCup:
+
+* Official GHC releases and prereleases will be made available by the release manager via GHCup's `vanilla` and `prerelease` channels, respectively
+* The aspiration is that, for tier 1 platforms, a GHC release (shipped in the GHCup `vanilla` channel) is of high enough quality to be a quality-assured release (shipped in the GHCup `default` channel) without patches.  
+  * If a downstream should need to repackage of release artifacts they are asked to consult with upstream such that the underlying issue can be addressed
+  * When a downstream packager needs to repackage a release, the steps should be documented, reproducible, and clearly visible to end-users such that issues that may stem from the modifications can be readily identified by upstream
+  * Binary distributions provided for non-tier-1 platforms should be clearly marked to users  
+
+[platform-tiers]: https://gitlab.haskell.org/ghc/ghc/-/wikis/platforms
+
+
+## 2.2. Boot libraries and versioning
+
+GHC ships in its source and binary distributions a small set of libraries
+depended upon by the compiler.
+
+* Boot library versions increase moving forward with time and major ghc versions. That is:  
+
+  > `ghc-major(X) >= ghc-major(Y) && date(X) > date(y)` implies 
+  > `core-lib-versions(X) >= core-lib-versions(Y)`  
+
+* The GHC team will notify boot library maintainers of the library versions
+  planned to be included in a GHC release with a reasonable time 
+  window (2 to 3 weeks) for the maintainer to recommend alternative versions.
+* Proposal coordination with the core libraries committee (CLC):
+  * Feature-changes to `base` should not be backported unless for security or similarly severe reasons.  
+  * CLC/GHC Proposals intended to land in a given release should be decided on and merged before a release branch is forked. Among other things this ensures that `Cabal` can support any added pragmas.
+  * If the GHC Team intends to include a CLC proposal in a GHC release they
+    must provide the CLC sufficient time (at least two weeks) to consider and
+    approve the proposal.
+
+
+* Boot library maintainers should provide Hackage releases and version control tags in a timely manner  
+* Boot library maintainers should notify GHC before increasing their dependency footprint (including package)  
+* Boot library maintainers should avoid unnecessary use of TemplateHaskell and gate any usage behind a Cabal flag  
+* GHC upstream appreciates notification from downstream maintainers regarding releases and major bugs that may require action from upstream
+
+
+# 3. Expectations around communication
+
+It is helpful to distinguish:
+
+* "**Push communication**" is:  
+  * Sent to a specific group of stakeholders that the GHC team thinks are relevant.  
+  * Opt out: recipients can opt out, of course, if they desire; and other
+    stakeholders can opt in.  
+
+* "**Opt-in communication**" is:  
+  * Broadcast to anyone who is interested.  
+  * Opt in: recipients will only receive it if they explicitly opt in, for
+    example by subscribing to an email list or reading the Haskell Discourse
+
+Ideally GHC's developers will anticipate all the issues that downstream consumers might
+encounter and draw their attention to them. In practice, that is too ambitious.
+For instance, changes in the file layout of an installed GHC may break a
+downstream distribution which happened to rely on the previous layout.
+
+Our plan is what you would expect: Try to be aware of the
+impact of changes made during development and gather feedback on issues in a
+timely fashion. Eventually make a candidate release, invite downstream users to
+try it out, be receptive to their feedback.
+
+We discussed three modes of communications: 
+
+1. **Proactive status email(s)** from GHC devs to a specified list of consumers,
+   explaining the release schedule, saying (so far as possible) what is
+   changing, inviting feedback (e.g. [this instance](https://mail.haskell.org/pipermail/ghc-releases/2024-November/000030.html)).
+   Such active communications should be expected on major developments in the
+   release process This is a form of "push" communication.
+
+2. **A shared channel**, devoted to releases, that allows release consumers to
+   chat informally with each other and with the release manager.
+
+   This is a form of "opt-in" communication, and does not replace (1)!
+   Proactive emails (1) should be cc'd to the shared channel, but we should not
+   rely on downstream consumers constantly monitoring the shared channel.  
+
+3. **Occassional meetings** where stakeholders can debrief previous releases, plan future
+   releases, and generally discuss.
+
+
+## 4.1 Terminology
+
+* **boot libraries**: libraries that come with GHC and that are difficult or impossible to re-install  
+* **alphas**: on the way to a release candidate, for integration testing, may be incomplete  
+* **release candidate**: this should be complete; in principle releasable.
+
+## 4.2 Communication channels
+
+Today GHC has two primary communications channels:
+
+* <ghc-devs@haskell.org> and `#ghc-devs:matrix.org`, both used for
+  communications within GHC's developer community.
+
+* The <https://discourse.haskell.org/> and <ghc-users@haskell.org> used primarily for release announcements and other major developments relevant to end-users
+
+To fulfill the above communications modes we propose to introduce the following
+new communications channels:
+
+* the <ghc-releases@haskell.org> email list which includes every stakeholder who
+  *should* be informed (e.g. authors of key libraries), or who would *like* to
+  be informed, about releases. The GHC team will proactively add stakeholders
+  to this list, unless they explicitly ask not to be added, but in addition any
+  one can add themselves.  
+
+* <ghc-boot-libraries@haskell.org>
+  mailing list for communication with maintainers of boot libraries. They are
+  likely not terribly interested in (comparably) lots of chatter in
+  <ghc-releases@haskell.org> and might prefer
+  just a single email per release.  
+
+* A Matrix channel, [`#haskell-releases:matrix.org`][haskell-releases],
+  for informal real-time chat about releases.
+
+* Every four months or so, we will hold a **regular check-in meeting** where a small
+  group of key consumers and GHC developers can meet to discuss how things
+  are going.  Scheduling such a meeting may be hard; but the goal is to
+  proactively reach out and invite a shared conversation about how to make
+  things better.  GHC devs should certainly expect people to push their
+  feedback to them, but sometimes things fall through the cracks, so "pulling
+  feedback" at intervals makes sure this doesn't happen, and conveys that GHC
+  devs actually care about said feedback.  
+
+[haskell-releases]: https://app.element.io/?updated=1.11.19#/room/#haskell-releases:matrix.org
+
+
+## 4.3 Communications for major releases of GHC
+
+* When a **major release branch is forked** or a **decision is taken** to make
+  a patch-level release, email to <ghc-releases@haskell.org> and
+  <ghc-devs@haskell.org>.
+  * Announcement that the branch is forked
+  * Preliminary announcement of the timetable
+  * Summary of what the release will contain, esp any destabilising changes. (Language changes are not so important for this purpose.)  
+  * Entry exists in the [GHC release status table](https://gitlab.haskell.org/ghc/ghc/-/wikis/GHC-Status), including a pointer to the milestone, which itself contains the timetable.  
+  * Announcing which version of which boot libraries will accompany the release  
+    * inviting feedback and version bumps  
+    * Goal: have the boot libraries sorted by alpha-2  
+    * TODO (AL): where does alpha-2 come from? Our latest discussion as summarised in [https://gitlab.haskell.org/ghc/ghc/-/wikis/GHC-status](https://gitlab.haskell.org/ghc/ghc/-/wikis/GHC-status) includes two deadlines: major releases should be finalized by branch fork (so pre-alpha-1) and minor releases should be finalized before the release candidate.
+* **When each alpha comes out**: email to <ghc-releases@haskell.org>, for information rather than action.
+* **When a release candidate comes out**: email to ghc-releases, inviting action.  
+  * Inviting downstream users to take it for a test drive  
+  * Giving a two week window for feedback.  
+
+  This step may be repeated if substantial changes are made, albeit perhaps with a shorter response window.
+
+## 4.4 Patch-level (aka minor) releases of GHC
+
+Even for patch-level releases, following the process of announcing a release candidate, with two weeks to try it out, is good practice.
+
+In particular, as for major releases:
+
+* Announce the upcoming release, with timetable etc.  
+* Indicate the reason for the release; what to look out for.  
+* Announce the release candidate as above, with time for downstream users to respond
+
+Otherwise the process is the same as the major release case but without alpha pre-releases, with a two week testing window for distribution prior to final release.
+
+## 4.5 Proactive announcements
+
+Beyond releases, if GHC HQ decides to change anything in terms of platform or architecture support, they should inform the community well in advance, at least by email to `ghc-devs`, and  to `ghc-releases`, and a Discourse post.  
+
+Examples:
+
+* If **a platform moves from one [Tier][platform-tiers] to another** (in either direction), this decision will be announced as soon as the decision is made, via at least the `ghc-releases` mailing list, hopefully allowing volunteers to step up to fix whatever made this decision necessary.  
+  * There will be a best-effort to also reach out to distro packagers directly if we know they might be affected.
+
+* **Major changes to how GHC is compiled from source** are communicated to users via [ghc-releases@haskell.org](mailto:ghc-releases@haskell.org) and the release notes
+
+* **Bindist changes**:  
+  * Significant changes to the top level file layout of installed bindists are communicated to downstream users via ghc-releases@haskell.org  
+  * Significant changes to the user-facing installation procedure (e.g. \`configure\` and \`make install\`) are communicated to users via the release notes and the release announcement.  
+  * Big changes to windows toolchains e.g. switching from gcc to clang are communicated via ghc-releases@haskell.org. Smaller changes like upgrades to the shipped versions are documented in release notes.
+
+Everyone recognises that however hard the GHC team tries to make proactive announcements, they may sometimes miss something important. These things are sometimes clearer looking back than looking forward.
+
+
-- 
GitLab


From 5ae51d8634fae80264c81ac3e5aeb4b815ad9c35 Mon Sep 17 00:00:00 2001
From: Simon Peyton Jones <simon.peytonjones@gmail.com>
Date: Tue, 7 Jan 2025 08:43:18 +0000
Subject: [PATCH 02/20] Update file release-management.mkd

---
 release-management.mkd | 38 ++++++++++++++++++++------------------
 1 file changed, 20 insertions(+), 18 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index fb299c3..504d5af 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -39,21 +39,21 @@ More specifically, we propose two significant changes:
 
 1. **Explicitly articulate a list of expectations (or invariants) about
    releases**, things that upstream producers undertake to maintain, and on
-   which downstream consumers can rely.   See Section 3.  
+   which downstream consumers can rely.   See Section 2.  
 
 2. **Define a communications plan** that describes how the upstream team will
-   communicate with downstream consumers.  See Section 4.
+   communicate with downstream consumers.  See Section 3.
 
 
 # 2. Expectations/invariants for GHC releases
 
 The goal of this section to is lay forth a set of technical invariants
-regarding GHC's distribution practices which downstream users can rely upon;
-the general aim of this is to ensure that GHC build products are fit for
-consumption without modification or augmentation by downstream distributors.
+regarding GHC's distribution practices. 
+The general aim of this is to ensure that GHC build products are fit for
+consumption, without modification or augmentation by downstream distributors.
 
-Here we seek to precisely articulate these expectations.
-GHC (e.g. packagers and end-users) can rely upon. These are offered as ideals
+Here we seek to precisely articulate the invariants that packagers and end-users
+can rely upon. These are offered as ideals
 to which both distributors and GHC developers both aspire. We recognize that
 not all of these ideals have been realized: while some we can guarantee today,
 others may be desireable but are not yet attainable. We will mark the latter with
@@ -72,13 +72,15 @@ to its wide adoption and close involvement with GHC upstream.
 
 ## 2.1. Release artifacts
 
-* GHC will clearly document which platforms releases support according to the establish [platform tier classification][platform-tiers]
+* GHC will clearly document which platforms are supported by each release, 
+according to the established [platform tier classification][platform-tiers]
 * Starting from a source distribution tarball, on all tier 1 platforms:  
   * GHC itself, including all of its boot libraries, must build to produce a functional compiler  
-  * The user’s guide and Haddock documentation for GHC and boot libraries must build  
-  * No such guarantees are provided for Tier 2 or lower platforms  
+  * The user’s guide and Haddock documentation for GHC and boot libraries must build 
+
+  No such guarantees are provided for Tier 2 or lower platforms  
 * Haddock documentation for GHC-maintained packages (e.g. `base`, `template-haskell`, the `ghc` library, `ghc-internal`, `ghc-prim`) is available on Hackage from day 0 and is fully functional.  
-* Bindists consistently include a minimum set of expected features. Specifically:  
+* Binary distributions (bindists) consistently include a minimum set of expected features. Specifically:  
   * the compiler, `iserv`, `ghci`, `haddock`, `unlit`
   * corresponding manual pages on platforms where these are supported
   * HTML users guide
@@ -93,7 +95,7 @@ to its wide adoption and close involvement with GHC upstream.
 * Binary distributions should provide a stable interface for configuration and installation (`configure`, `make`, `hadrian`)  
   * For this to happen one needs to define the desired feature set [🔴], after which tests can be added to ensure it is maintained.  
   * The same is true for building from source. This requires hadrian features to be split into “stable” user facing and development workflow features [🔴]
-* Ensure testsuite distribution passes across all supported platforms and configurations.
+* The testsuite distribution passes across all supported platforms and configurations.
 
 The GHC and GHCup teams will take an active role in providing releases via GHCup:
 
@@ -109,15 +111,15 @@ The GHC and GHCup teams will take an active role in providing releases via GHCup
 ## 2.2. Boot libraries and versioning
 
 GHC ships in its source and binary distributions a small set of libraries
-depended upon by the compiler.
+depended upon by the compiler.  These are the *boot libraries*.
 
-* Boot library versions increase moving forward with time and major ghc versions. That is:  
+* The version of a boot library increase moving forward with time and major ghc versions. That is:  
 
   > `ghc-major(X) >= ghc-major(Y) && date(X) > date(y)` implies 
   > `core-lib-versions(X) >= core-lib-versions(Y)`  
 
 * The GHC team will notify boot library maintainers of the library versions
-  planned to be included in a GHC release with a reasonable time 
+  planned to be included in an upcoming GHC release with a reasonable time 
   window (2 to 3 weeks) for the maintainer to recommend alternative versions.
 * Proposal coordination with the core libraries committee (CLC):
   * Feature-changes to `base` should not be backported unless for security or similarly severe reasons.  
@@ -149,13 +151,13 @@ It is helpful to distinguish:
 
 Ideally GHC's developers will anticipate all the issues that downstream consumers might
 encounter and draw their attention to them. In practice, that is too ambitious.
-For instance, changes in the file layout of an installed GHC may break a
+One real example: a change in the file layout of an installed GHC inadvertently broke a
 downstream distribution which happened to rely on the previous layout.
 
-Our plan is what you would expect: Try to be aware of the
+Our plan is what you would expect: try to be aware of the
 impact of changes made during development and gather feedback on issues in a
 timely fashion. Eventually make a candidate release, invite downstream users to
-try it out, be receptive to their feedback.
+try it out, amd be receptive to their feedback.
 
 We discussed three modes of communications: 
 
-- 
GitLab


From d0223233e75f27165d57598ddcc70a96b06558dc Mon Sep 17 00:00:00 2001
From: Simon Peyton Jones <simon.peytonjones@gmail.com>
Date: Tue, 7 Jan 2025 08:49:02 +0000
Subject: [PATCH 03/20] Update file release-management.mkd

---
 release-management.mkd | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 504d5af..0edf384 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -178,13 +178,13 @@ We discussed three modes of communications:
    releases, and generally discuss.
 
 
-## 4.1 Terminology
+## 3.1 Terminology
 
 * **boot libraries**: libraries that come with GHC and that are difficult or impossible to re-install  
 * **alphas**: on the way to a release candidate, for integration testing, may be incomplete  
 * **release candidate**: this should be complete; in principle releasable.
 
-## 4.2 Communication channels
+## 3.2 Communication channels
 
 Today GHC has two primary communications channels:
 
@@ -223,7 +223,7 @@ new communications channels:
 [haskell-releases]: https://app.element.io/?updated=1.11.19#/room/#haskell-releases:matrix.org
 
 
-## 4.3 Communications for major releases of GHC
+## 3.3 Communications for major releases of GHC
 
 * When a **major release branch is forked** or a **decision is taken** to make
   a patch-level release, email to <ghc-releases@haskell.org> and
@@ -243,7 +243,7 @@ new communications channels:
 
   This step may be repeated if substantial changes are made, albeit perhaps with a shorter response window.
 
-## 4.4 Patch-level (aka minor) releases of GHC
+## 3.4 Patch-level (aka minor) releases of GHC
 
 Even for patch-level releases, following the process of announcing a release candidate, with two weeks to try it out, is good practice.
 
@@ -255,7 +255,7 @@ In particular, as for major releases:
 
 Otherwise the process is the same as the major release case but without alpha pre-releases, with a two week testing window for distribution prior to final release.
 
-## 4.5 Proactive announcements
+## 3.5 Proactive announcements
 
 Beyond releases, if GHC HQ decides to change anything in terms of platform or architecture support, they should inform the community well in advance, at least by email to `ghc-devs`, and  to `ghc-releases`, and a Discourse post.  
 
-- 
GitLab


From 2a16925641b0ed0882cde1ac4449f208fcbcb520 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Wed, 8 Jan 2025 21:14:43 -0500
Subject: [PATCH 04/20] Final pass

---
 release-management.mkd | 182 ++++++++++++++++++++++++++---------------
 1 file changed, 116 insertions(+), 66 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 0edf384..a7d13c9 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -11,7 +11,9 @@ These notes summarise a discussion to improve GHC's release processes,
 especially concerning the partnership between
 
 * "upstream producers": those producing GHC's releases (roughly: the GHC team), and
-* "downstream consumers": those consuming them (roughly: ghcup, library authors, Stack team, Stackage, Linux distros including Nix, HLS, Cabal, Core Libraries Committee).
+* "downstream consumers": those consuming them (roughly: ghcup, library
+  authors, Stack team, Stackage, Linux distros including Nix, HLS, Cabal, Core
+  Libraries Committee).
 
 This document is a work in progress. 
 
@@ -72,15 +74,21 @@ to its wide adoption and close involvement with GHC upstream.
 
 ## 2.1. Release artifacts
 
-* GHC will clearly document which platforms are supported by each release, 
-according to the established [platform tier classification][platform-tiers]
-* Starting from a source distribution tarball, on all tier 1 platforms:  
-  * GHC itself, including all of its boot libraries, must build to produce a functional compiler  
-  * The user’s guide and Haddock documentation for GHC and boot libraries must build 
+* Alpha prereleases will be published for testing purposes in preparation for new major releases
+* Release candidates will be published for testing purposes prior to both major and minor releases;
+  a testing period of at least two weeks between the publication of a release
+  candidate and the final release will be provided
+* GHC will clearly document which platforms are supported by each release according to the
+  established [platform tier classification][platform-tiers]
+* Starting from a source distribution tarball, on all tier 1 platforms:
 
-  No such guarantees are provided for Tier 2 or lower platforms  
-* Haddock documentation for GHC-maintained packages (e.g. `base`, `template-haskell`, the `ghc` library, `ghc-internal`, `ghc-prim`) is available on Hackage from day 0 and is fully functional.  
-* Binary distributions (bindists) consistently include a minimum set of expected features. Specifically:  
+  * GHC itself, including all of its boot libraries, must build to produce a functional compiler  
+  * The user’s guide and Haddock documentation for GHC and boot libraries must build  
+  * No such guarantees are provided for Tier 2 or lower platforms  
+* Haddock documentation for GHC-maintained packages (e.g. `base`,
+  `template-haskell`, the `ghc` library, `ghc-internal`, `ghc-prim`) is
+  available on Hackage from day 0 and is fully functional.  
+* Binary distributions consistently include a minimum set of expected features. Specifically:  
   * the compiler, `iserv`, `ghci`, `haddock`, `unlit`
   * corresponding manual pages on platforms where these are supported
   * HTML users guide
@@ -91,18 +99,31 @@ according to the established [platform tier classification][platform-tiers]
   Note that certain characteristics of bindists are inherently different
   between platforms (e.g. static vs dynamic linkage, `libffi`, `gmp`, `libc`
   versions, etc). These attributes are not covered in the above.
-* The `-testsuite` distribution tarball should be tested regularly (e.g. via the nightly validation pipeline) via CI [🔴]
-* Binary distributions should provide a stable interface for configuration and installation (`configure`, `make`, `hadrian`)  
-  * For this to happen one needs to define the desired feature set [🔴], after which tests can be added to ensure it is maintained.  
-  * The same is true for building from source. This requires hadrian features to be split into “stable” user facing and development workflow features [🔴]
+* The `-testsuite` distribution tarball should be tested regularly (e.g. via
+  the nightly validation pipeline) via CI [🔴]
+* Binary distributions should provide a stable interface for configuration and
+  installation (`configure`, `make`, `hadrian`)  
+  * For this to happen one needs to define the desired feature set [🔴], after
+    which tests can be added to ensure it is maintained.  
+  * The same is true for building from source. This requires hadrian features
+    to be split into “stable” user facing and development workflow features
+    [🔴]
 * The testsuite distribution passes across all supported platforms and configurations.
 
 The GHC and GHCup teams will take an active role in providing releases via GHCup:
 
-* Official GHC releases and prereleases will be made available by the release manager via GHCup's `vanilla` and `prerelease` channels, respectively
-* The aspiration is that, for tier 1 platforms, a GHC release (shipped in the GHCup `vanilla` channel) is of high enough quality to be a quality-assured release (shipped in the GHCup `default` channel) without patches.  
-  * If a downstream should need to repackage of release artifacts they are asked to consult with upstream such that the underlying issue can be addressed
-  * When a downstream packager needs to repackage a release, the steps should be documented, reproducible, and clearly visible to end-users such that issues that may stem from the modifications can be readily identified by upstream
+* Official GHC releases and prereleases will be made available by the release
+  manager via GHCup's `vanilla` and `prerelease` channels, respectively
+* The aspiration is that, for tier 1 platforms, a GHC release (shipped in the
+  GHCup `vanilla` channel) is of high enough quality to be a quality-assured
+  release (shipped in the GHCup `default` channel) without patches.  
+  * If a downstream should need to repackage of release artifacts they are
+    asked to consult with upstream such that the underlying issue can be
+    addressed
+  * When a downstream packager needs to repackage a release, the steps should
+    be documented, reproducible, and clearly visible to end-users such that
+    issues that may stem from the modifications can be readily identified by
+    upstream
   * Binary distributions provided for non-tier-1 platforms should be clearly marked to users  
 
 [platform-tiers]: https://gitlab.haskell.org/ghc/ghc/-/wikis/platforms
@@ -123,16 +144,22 @@ depended upon by the compiler.  These are the *boot libraries*.
   window (2 to 3 weeks) for the maintainer to recommend alternative versions.
 * Proposal coordination with the core libraries committee (CLC):
   * Feature-changes to `base` should not be backported unless for security or similarly severe reasons.  
-  * CLC/GHC Proposals intended to land in a given release should be decided on and merged before a release branch is forked. Among other things this ensures that `Cabal` can support any added pragmas.
+  * CLC/GHC Proposals intended to land in a given release should be decided on
+    and merged before a release branch is forked. Among other things this
+    ensures that `Cabal` can support any added pragmas.
   * If the GHC Team intends to include a CLC proposal in a GHC release they
     must provide the CLC sufficient time (at least two weeks) to consider and
     approve the proposal.
 
 
-* Boot library maintainers should provide Hackage releases and version control tags in a timely manner  
-* Boot library maintainers should notify GHC before increasing their dependency footprint (including package)  
-* Boot library maintainers should avoid unnecessary use of TemplateHaskell and gate any usage behind a Cabal flag  
-* GHC upstream appreciates notification from downstream maintainers regarding releases and major bugs that may require action from upstream
+* Boot library maintainers should provide Hackage releases and version control
+  tags in a timely manner  
+* Boot library maintainers should notify GHC before increasing their dependency
+  footprint (including package)  
+* Boot library maintainers should avoid unnecessary use of TemplateHaskell and
+  gate any usage behind a Cabal flag  
+* GHC upstream appreciates notification from downstream maintainers regarding
+  releases and major bugs that may require action from upstream
 
 
 # 3. Expectations around communication
@@ -157,15 +184,15 @@ downstream distribution which happened to rely on the previous layout.
 Our plan is what you would expect: try to be aware of the
 impact of changes made during development and gather feedback on issues in a
 timely fashion. Eventually make a candidate release, invite downstream users to
-try it out, amd be receptive to their feedback.
+try it out and be receptive to their feedback.
 
 We discussed three modes of communications: 
 
 1. **Proactive status email(s)** from GHC devs to a specified list of consumers,
    explaining the release schedule, saying (so far as possible) what is
-   changing, inviting feedback (e.g. [this instance](https://mail.haskell.org/pipermail/ghc-releases/2024-November/000030.html)).
+   changing, inviting feedback (e.g. [the GHC 9.12.1 status update](https://mail.haskell.org/pipermail/ghc-releases/2024-November/000030.html)).
    Such active communications should be expected on major developments in the
-   release process This is a form of "push" communication.
+   release process. This is a form of "push" communication.
 
 2. **A shared channel**, devoted to releases, that allows release consumers to
    chat informally with each other and with the release manager.
@@ -180,7 +207,6 @@ We discussed three modes of communications:
 
 ## 3.1 Terminology
 
-* **boot libraries**: libraries that come with GHC and that are difficult or impossible to re-install  
 * **alphas**: on the way to a release candidate, for integration testing, may be incomplete  
 * **release candidate**: this should be complete; in principle releasable.
 
@@ -191,7 +217,9 @@ Today GHC has two primary communications channels:
 * <ghc-devs@haskell.org> and `#ghc-devs:matrix.org`, both used for
   communications within GHC's developer community.
 
-* The <https://discourse.haskell.org/> and <ghc-users@haskell.org> used primarily for release announcements and other major developments relevant to end-users
+* The <https://discourse.haskell.org/> and <ghc-users@haskell.org> used
+  primarily for release announcements and other major developments relevant to
+  end-users
 
 To fulfill the above communications modes we propose to introduce the following
 new communications channels:
@@ -211,66 +239,88 @@ new communications channels:
 * A Matrix channel, [`#haskell-releases:matrix.org`][haskell-releases],
   for informal real-time chat about releases.
 
-* Every four months or so, we will hold a **regular check-in meeting** where a small
-  group of key consumers and GHC developers can meet to discuss how things
-  are going.  Scheduling such a meeting may be hard; but the goal is to
+* Every four months or so, we will hold a **regular check-in meeting** where a
+  small group of key consumers and GHC developers can meet to discuss how
+  things are going.  Scheduling such a meeting may be hard; but the goal is to
   proactively reach out and invite a shared conversation about how to make
-  things better.  GHC devs should certainly expect people to push their
-  feedback to them, but sometimes things fall through the cracks, so "pulling
-  feedback" at intervals makes sure this doesn't happen, and conveys that GHC
-  devs actually care about said feedback.  
+  things better. GHC devs should certainly expect people to push their feedback
+  to them, but sometimes things fall through the cracks, so "pulling feedback"
+  at intervals makes sure this doesn't happen, and conveys that GHC devs
+  actually care about said feedback.  
 
 [haskell-releases]: https://app.element.io/?updated=1.11.19#/room/#haskell-releases:matrix.org
 
 
-## 3.3 Communications for major releases of GHC
+## 4.3 Communications for major releases of GHC
+
+The status of major GHC releases will be communicated as follows:
 
-* When a **major release branch is forked** or a **decision is taken** to make
-  a patch-level release, email to <ghc-releases@haskell.org> and
-  <ghc-devs@haskell.org>.
-  * Announcement that the branch is forked
-  * Preliminary announcement of the timetable
-  * Summary of what the release will contain, esp any destabilising changes. (Language changes are not so important for this purpose.)  
-  * Entry exists in the [GHC release status table](https://gitlab.haskell.org/ghc/ghc/-/wikis/GHC-Status), including a pointer to the milestone, which itself contains the timetable.  
-  * Announcing which version of which boot libraries will accompany the release  
-    * inviting feedback and version bumps  
-    * Goal: have the boot libraries sorted by alpha-2  
-    * TODO (AL): where does alpha-2 come from? Our latest discussion as summarised in [https://gitlab.haskell.org/ghc/ghc/-/wikis/GHC-status](https://gitlab.haskell.org/ghc/ghc/-/wikis/GHC-status) includes two deadlines: major releases should be finalized by branch fork (so pre-alpha-1) and minor releases should be finalized before the release candidate.
-* **When each alpha comes out**: email to <ghc-releases@haskell.org>, for information rather than action.
-* **When a release candidate comes out**: email to ghc-releases, inviting action.  
-  * Inviting downstream users to take it for a test drive  
-  * Giving a two week window for feedback.  
+1. A few weeks before the fork date send email to <ghc-boot-libraries@haskell.org> containing:
+   * Announcing which version of which boot libraries the GHC team proposes to be included in the release  
+   * inviting feedback and version bumps
+   * Goal: have the boot libraries sorted by alpha-2  
+1. When a major release branch is forked, email to <ghc-releases@haskell.org>
+   and <ghc-devs@haskell.org> containing:
+  * an announcement that the branch fork has happened
+  * a preliminary announcement of the timetable  
+  * a summary of what the release is planned to contain, especially any
+    destabilising changes relevant to distributors and testers (N.B. language
+    changes are not so important for this purpose).
+1. Ensure that an entry exists in the [GHC release status table][ghc-status],
+   including a pointer to the milestone, which itself contains the timetable.  
+1. When each alpha comes out: email to <ghc-releases@haskell.org> for information rather than action
+1. When a release candidate comes out: email to <ghc-releases@haskell.org> inviting action:
+  * Invite downstream users to take it for a test drive  
+  * There will be at least a two-week window between the release candidate and
+    final release for testing and feedback
+  * This step may be repeated if substantial changes are made, albeit perhaps
+    with a shorter response window.
 
-  This step may be repeated if substantial changes are made, albeit perhaps with a shorter response window.
+[ghc-status]: https://gitlab.haskell.org/ghc/ghc/-/wikis/GHC-Status
 
-## 3.4 Patch-level (aka minor) releases of GHC
+## 4.4 Patch-level (aka minor) releases of GHC
 
-Even for patch-level releases, following the process of announcing a release candidate, with two weeks to try it out, is good practice.
+Even for patch-level releases, following the process of announcing a release
+candidate, with two weeks to try it out, is good practice.
 
 In particular, as for major releases:
 
 * Announce the upcoming release, with timetable etc.  
 * Indicate the reason for the release; what to look out for.  
-* Announce the release candidate as above, with time for downstream users to respond
+* Announce the release candidate as above, with time for downstream users to
+  respond
 
-Otherwise the process is the same as the major release case but without alpha pre-releases, with a two week testing window for distribution prior to final release.
+Otherwise the process is the same as the major release case but without alpha
+pre-releases, with a two week testing window for distribution prior to final
+release.
 
 ## 3.5 Proactive announcements
 
-Beyond releases, if GHC HQ decides to change anything in terms of platform or architecture support, they should inform the community well in advance, at least by email to `ghc-devs`, and  to `ghc-releases`, and a Discourse post.  
+Beyond releases, if GHC HQ decides to change anything in terms of platform or
+architecture support, they should inform the community well in advance, at
+least by email to `ghc-devs`, to `ghc-releases`, and a Discourse post.  
 
-Examples:
+Examples of such announcements include:
 
-* If **a platform moves from one [Tier][platform-tiers] to another** (in either direction), this decision will be announced as soon as the decision is made, via at least the `ghc-releases` mailing list, hopefully allowing volunteers to step up to fix whatever made this decision necessary.  
-  * There will be a best-effort to also reach out to distro packagers directly if we know they might be affected.
+* If **a platform moves from one [tier][platform-tiers] to another** (in either
+  direction):
+  * the decision will be announced as soon as possible, via at least the
+    `ghc-releases` mailing list, hopefully allowing volunteers to step up to
+    fix whatever made this decision necessary.  
+  * there will be a best-effort to also reach out to distributors and packagers
+    directly if we know they might be affected.
 
-* **Major changes to how GHC is compiled from source** are communicated to users via [ghc-releases@haskell.org](mailto:ghc-releases@haskell.org) and the release notes
+* **Major changes to how GHC is compiled from source** are communicated to
+  users via [ghc-releases@haskell.org](mailto:ghc-releases@haskell.org) and the
+  release notes
 
 * **Bindist changes**:  
-  * Significant changes to the top level file layout of installed bindists are communicated to downstream users via ghc-releases@haskell.org  
-  * Significant changes to the user-facing installation procedure (e.g. \`configure\` and \`make install\`) are communicated to users via the release notes and the release announcement.  
-  * Big changes to windows toolchains e.g. switching from gcc to clang are communicated via ghc-releases@haskell.org. Smaller changes like upgrades to the shipped versions are documented in release notes.
-
-Everyone recognises that however hard the GHC team tries to make proactive announcements, they may sometimes miss something important. These things are sometimes clearer looking back than looking forward.
-
+  * Significant changes to the top level file layout of installed bindists are
+    communicated to downstream users via ghc-releases@haskell.org  
+  * Significant changes to the user-facing installation procedure (e.g.
+    \`configure\` and \`make install\`) are communicated to users via the
+    release notes and the release announcement.  
+  * Big changes to windows toolchains e.g. switching from gcc to clang are
+    communicated via ghc-releases@haskell.org. Smaller changes like upgrades to
+    the shipped versions are documented in release notes.
 
-- 
GitLab


From d9c60110b1fb72caed7ec0799e8aae4c3767adbe Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Wed, 8 Jan 2025 21:27:06 -0500
Subject: [PATCH 05/20] Address feedback from Simon

---
 release-management.mkd | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index a7d13c9..0c48a35 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -99,8 +99,6 @@ to its wide adoption and close involvement with GHC upstream.
   Note that certain characteristics of bindists are inherently different
   between platforms (e.g. static vs dynamic linkage, `libffi`, `gmp`, `libc`
   versions, etc). These attributes are not covered in the above.
-* The `-testsuite` distribution tarball should be tested regularly (e.g. via
-  the nightly validation pipeline) via CI [🔴]
 * Binary distributions should provide a stable interface for configuration and
   installation (`configure`, `make`, `hadrian`)  
   * For this to happen one needs to define the desired feature set [🔴], after
@@ -132,7 +130,8 @@ The GHC and GHCup teams will take an active role in providing releases via GHCup
 ## 2.2. Boot libraries and versioning
 
 GHC ships in its source and binary distributions a small set of libraries
-depended upon by the compiler.  These are the *boot libraries*.
+depended upon by the compiler.  These are the *boot libraries*; these are
+summarized on the [GHC wiki][library-versions].
 
 * The version of a boot library increase moving forward with time and major ghc versions. That is:  
 
@@ -143,7 +142,9 @@ depended upon by the compiler.  These are the *boot libraries*.
   planned to be included in an upcoming GHC release with a reasonable time 
   window (2 to 3 weeks) for the maintainer to recommend alternative versions.
 * Proposal coordination with the core libraries committee (CLC):
-  * Feature-changes to `base` should not be backported unless for security or similarly severe reasons.  
+  * Changes to the interfaces of `base` and other core libraries under GHC
+    control should not be made in minor releases. Exceptions may be made for
+    security vulnerabilities and severe correctness issues.
   * CLC/GHC Proposals intended to land in a given release should be decided on
     and merged before a release branch is forked. Among other things this
     ensures that `Cabal` can support any added pragmas.
@@ -151,7 +152,6 @@ depended upon by the compiler.  These are the *boot libraries*.
     must provide the CLC sufficient time (at least two weeks) to consider and
     approve the proposal.
 
-
 * Boot library maintainers should provide Hackage releases and version control
   tags in a timely manner  
 * Boot library maintainers should notify GHC before increasing their dependency
@@ -161,6 +161,8 @@ depended upon by the compiler.  These are the *boot libraries*.
 * GHC upstream appreciates notification from downstream maintainers regarding
   releases and major bugs that may require action from upstream
 
+[library-versions]: https://gitlab.haskell.org/ghc/ghc/-/wikis/commentary/libraries/version-history
+
 
 # 3. Expectations around communication
 
@@ -212,7 +214,7 @@ We discussed three modes of communications:
 
 ## 3.2 Communication channels
 
-Today GHC has two primary communications channels:
+GHC developers use the following communications channels:
 
 * <ghc-devs@haskell.org> and `#ghc-devs:matrix.org`, both used for
   communications within GHC's developer community.
@@ -221,20 +223,17 @@ Today GHC has two primary communications channels:
   primarily for release announcements and other major developments relevant to
   end-users
 
-To fulfill the above communications modes we propose to introduce the following
-new communications channels:
-
 * the <ghc-releases@haskell.org> email list which includes every stakeholder who
   *should* be informed (e.g. authors of key libraries), or who would *like* to
   be informed, about releases. The GHC team will proactively add stakeholders
   to this list, unless they explicitly ask not to be added, but in addition any
-  one can add themselves.  
+  one can add themselves. This is a "push" communications channel.
 
 * <ghc-boot-libraries@haskell.org>
   mailing list for communication with maintainers of boot libraries. They are
   likely not terribly interested in (comparably) lots of chatter in
-  <ghc-releases@haskell.org> and might prefer
-  just a single email per release.  
+  <ghc-releases@haskell.org> and might prefer just a single email per release.  
+  This is a "push" communications channel.
 
 * A Matrix channel, [`#haskell-releases:matrix.org`][haskell-releases],
   for informal real-time chat about releases.
-- 
GitLab


From 917e887348935a0f28296b49e2cbe1233dcefe2e Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Tue, 21 Jan 2025 08:55:41 -0500
Subject: [PATCH 06/20] Address various feedback

---
 release-management.mkd | 42 ++++++++++++++++++++++++------------------
 1 file changed, 24 insertions(+), 18 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 0c48a35..7004406 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -15,8 +15,6 @@ especially concerning the partnership between
   authors, Stack team, Stackage, Linux distros including Nix, HLS, Cabal, Core
   Libraries Committee).
 
-This document is a work in progress. 
-
 In order to understand where we can improve it is important
 to understand the areas where our downstream users struggle. We have started to
 collect some such reports from downstream stakeholders in [this
@@ -59,7 +57,7 @@ can rely upon. These are offered as ideals
 to which both distributors and GHC developers both aspire. We recognize that
 not all of these ideals have been realized: while some we can guarantee today,
 others may be desireable but are not yet attainable. We will mark the latter with
-a [🔴] to indicate that help could be used in these areas.
+a (🔴) to indicate that help could be used in these areas.
 
 Regardless, by specifying these goals in concrete terms we hope to better prioritize
 work on GHC to improve the downstream experience. Moreover, this list can serve
@@ -83,12 +81,14 @@ to its wide adoption and close involvement with GHC upstream.
 * Starting from a source distribution tarball, on all tier 1 platforms:
 
   * GHC itself, including all of its boot libraries, must build to produce a functional compiler  
-  * The user’s guide and Haddock documentation for GHC and boot libraries must build  
+  * The user’s guide, manual page (where applicable) and Haddock documentation
+    for GHC and boot libraries must build  
   * No such guarantees are provided for Tier 2 or lower platforms  
 * Haddock documentation for GHC-maintained packages (e.g. `base`,
   `template-haskell`, the `ghc` library, `ghc-internal`, `ghc-prim`) is
-  available on Hackage from day 0 and is fully functional.  
-* Binary distributions consistently include a minimum set of expected features. Specifically:  
+  available on Hackage on the day of release and is fully functional.  
+* Binary distributions provided for tier 1 platforms consistently include a minimum set
+  of expected features. Specifically:  
   * the compiler, `iserv`, `ghci`, `haddock`, `unlit`
   * corresponding manual pages on platforms where these are supported
   * HTML users guide
@@ -100,13 +100,16 @@ to its wide adoption and close involvement with GHC upstream.
   between platforms (e.g. static vs dynamic linkage, `libffi`, `gmp`, `libc`
   versions, etc). These attributes are not covered in the above.
 * Binary distributions should provide a stable interface for configuration and
-  installation (`configure`, `make`, `hadrian`)  
-  * For this to happen one needs to define the desired feature set [🔴], after
+  installation (`configure`, `make`, `ghc-toolchain`)
+  (see [GHC #25669](https://gitlab.haskell.org/ghc/ghc/-/issues/25669)).
+  * For this to happen one needs to define the desired feature set (🔴), after
     which tests can be added to ensure it is maintained.  
-  * The same is true for building from source. This requires hadrian features
-    to be split into “stable” user facing and development workflow features
-    [🔴]
-* The testsuite distribution passes across all supported platforms and configurations.
+  * The same is true for building from source. This requires that Hadrian features
+    be split into “stable” user facing and development workflow features
+    (🔴)
+* The testsuite distribution (i.e. `ghc-X.Y.Z-testsuite.tar`) passes across all
+  supported platforms and configurations (🔴)
+  (see [GHC #25670](https://gitlab.haskell.org/ghc/ghc/-/issues/25670)).
 
 The GHC and GHCup teams will take an active role in providing releases via GHCup:
 
@@ -142,9 +145,10 @@ summarized on the [GHC wiki][library-versions].
   planned to be included in an upcoming GHC release with a reasonable time 
   window (2 to 3 weeks) for the maintainer to recommend alternative versions.
 * Proposal coordination with the core libraries committee (CLC):
-  * Changes to the interfaces of `base` and other core libraries under GHC
-    control should not be made in minor releases. Exceptions may be made for
-    security vulnerabilities and severe correctness issues.
+  * Changes to the interfaces of `base`, `template-haskell`, and other core
+    libraries under GHC control should not be made in minor releases.
+    Exceptions may be made for security vulnerabilities and severe correctness
+    issues.
   * CLC/GHC Proposals intended to land in a given release should be decided on
     and merged before a release branch is forked. Among other things this
     ensures that `Cabal` can support any added pragmas.
@@ -156,8 +160,9 @@ summarized on the [GHC wiki][library-versions].
   tags in a timely manner  
 * Boot library maintainers should notify GHC before increasing their dependency
   footprint (including package)  
-* Boot library maintainers should avoid unnecessary use of TemplateHaskell and
-  gate any usage behind a Cabal flag  
+* Boot library maintainers should avoid unnecessary use of `TemplateHaskell` and
+  gate any usage behind a Cabal flag as such usage poses a challenge for
+  bootstrapping GHC
 * GHC upstream appreciates notification from downstream maintainers regarding
   releases and major bugs that may require action from upstream
 
@@ -206,6 +211,7 @@ We discussed three modes of communications:
 3. **Occassional meetings** where stakeholders can debrief previous releases, plan future
    releases, and generally discuss.
 
+In all communications we will strive to treat with other with respect and courtesy.
 
 ## 3.1 Terminology
 
@@ -295,7 +301,7 @@ release.
 
 ## 3.5 Proactive announcements
 
-Beyond releases, if GHC HQ decides to change anything in terms of platform or
+Beyond releases, if GHC HQ decides to make major changes in platform or
 architecture support, they should inform the community well in advance, at
 least by email to `ghc-devs`, to `ghc-releases`, and a Discourse post.  
 
-- 
GitLab


From a2d8f2344f7ac4adf5c0441ca065af2d91d08045 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Tue, 21 Jan 2025 17:38:15 -0500
Subject: [PATCH 07/20] release-mgmt: Fix a few minor points

---
 release-management.mkd | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 7004406..4ec7fb1 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -136,7 +136,8 @@ GHC ships in its source and binary distributions a small set of libraries
 depended upon by the compiler.  These are the *boot libraries*; these are
 summarized on the [GHC wiki][library-versions].
 
-* The version of a boot library increase moving forward with time and major ghc versions. That is:  
+* The version of a boot library typically increase moving forward with time and
+  major GHC versions. That is:  
 
   > `ghc-major(X) >= ghc-major(Y) && date(X) > date(y)` implies 
   > `core-lib-versions(X) >= core-lib-versions(Y)`  
@@ -195,7 +196,7 @@ try it out and be receptive to their feedback.
 
 We discussed three modes of communications: 
 
-1. **Proactive status email(s)** from GHC devs to a specified list of consumers,
+1. **Proactive status email(s)** from GHC developers to a specified list of consumers,
    explaining the release schedule, saying (so far as possible) what is
    changing, inviting feedback (e.g. [the GHC 9.12.1 status update](https://mail.haskell.org/pipermail/ghc-releases/2024-November/000030.html)).
    Such active communications should be expected on major developments in the
@@ -233,24 +234,29 @@ GHC developers use the following communications channels:
   *should* be informed (e.g. authors of key libraries), or who would *like* to
   be informed, about releases. The GHC team will proactively add stakeholders
   to this list, unless they explicitly ask not to be added, but in addition any
-  one can add themselves. This is a "push" communications channel.
+  one can add themselves. While this list is open to the public GHC HQ will add
+  members to this list as appropriate (who naturally, may opt out if
+  desireable).
 
 * <ghc-boot-libraries@haskell.org>
   mailing list for communication with maintainers of boot libraries. They are
   likely not terribly interested in (comparably) lots of chatter in
   <ghc-releases@haskell.org> and might prefer just a single email per release.  
-  This is a "push" communications channel.
+  Similar to `ghc-releases@`, GHC HQ will ensure that boot library maintainers
+  are added to this list appropriate.
 
 * A Matrix channel, [`#haskell-releases:matrix.org`][haskell-releases],
-  for informal real-time chat about releases.
+  for informal real-time chat about releases. Announcements will be made over
+  this channel, but never exclusively on this channel (with `ghc-releases`
+  being the primary channel).
 
 * Every four months or so, we will hold a **regular check-in meeting** where a
   small group of key consumers and GHC developers can meet to discuss how
   things are going.  Scheduling such a meeting may be hard; but the goal is to
   proactively reach out and invite a shared conversation about how to make
-  things better. GHC devs should certainly expect people to push their feedback
+  things better. GHC developers should certainly expect people to push their feedback
   to them, but sometimes things fall through the cracks, so "pulling feedback"
-  at intervals makes sure this doesn't happen, and conveys that GHC devs
+  at intervals makes sure this doesn't happen, and conveys that GHC developers
   actually care about said feedback.  
 
 [haskell-releases]: https://app.element.io/?updated=1.11.19#/room/#haskell-releases:matrix.org
@@ -303,7 +309,7 @@ release.
 
 Beyond releases, if GHC HQ decides to make major changes in platform or
 architecture support, they should inform the community well in advance, at
-least by email to `ghc-devs`, to `ghc-releases`, and a Discourse post.  
+least by email to `ghc-devs@`, to `ghc-releases@`, and a Discourse post.  
 
 Examples of such announcements include:
 
-- 
GitLab


From 4f3edec7ba758095e55f81fe3347b8876b7ecd00 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Tue, 21 Jan 2025 17:52:25 -0500
Subject: [PATCH 08/20] rel-mgmt: More iteration

---
 release-management.mkd | 53 +++++++++++++++++-------------------------
 1 file changed, 21 insertions(+), 32 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 4ec7fb1..76b1d8e 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -142,9 +142,13 @@ summarized on the [GHC wiki][library-versions].
   > `ghc-major(X) >= ghc-major(Y) && date(X) > date(y)` implies 
   > `core-lib-versions(X) >= core-lib-versions(Y)`  
 
+* GHC HQ will not perform major version bumps of boot libraries in minor
+  compiler releases.
+
 * The GHC team will notify boot library maintainers of the library versions
   planned to be included in an upcoming GHC release with a reasonable time 
   window (2 to 3 weeks) for the maintainer to recommend alternative versions.
+
 * Proposal coordination with the core libraries committee (CLC):
   * Changes to the interfaces of `base`, `template-haskell`, and other core
     libraries under GHC control should not be made in minor releases.
@@ -159,11 +163,14 @@ summarized on the [GHC wiki][library-versions].
 
 * Boot library maintainers should provide Hackage releases and version control
   tags in a timely manner  
+
 * Boot library maintainers should notify GHC before increasing their dependency
   footprint (including package)  
-* Boot library maintainers should avoid unnecessary use of `TemplateHaskell` and
-  gate any usage behind a Cabal flag as such usage poses a challenge for
-  bootstrapping GHC
+
+* GHC upstream expects that boot library maintainers make conditional or
+  otherwise avoid unnecessary use of `TemplateHaskell` as such usage poses a
+  challenge for bootstrapping and cross-compiling GHC
+
 * GHC upstream appreciates notification from downstream maintainers regarding
   releases and major bugs that may require action from upstream
 
@@ -172,7 +179,13 @@ summarized on the [GHC wiki][library-versions].
 
 # 3. Expectations around communication
 
-It is helpful to distinguish:
+We want to ensure that GHC's communications is clear and easily heard.
+While ideally GHC's developers will anticipate all issues that downstream
+consumers might encounter and work to mitigate them prior to release; however,
+in practice this is too ambitious. Robust communications channels ensure that
+lapses are quickly discovered and addressed.
+
+When considering communications modes, it is helpful to distinguish:
 
 * "**Push communication**" is:  
   * Sent to a specific group of stakeholders that the GHC team thinks are relevant.  
@@ -184,35 +197,11 @@ It is helpful to distinguish:
   * Opt in: recipients will only receive it if they explicitly opt in, for
     example by subscribing to an email list or reading the Haskell Discourse
 
-Ideally GHC's developers will anticipate all the issues that downstream consumers might
-encounter and draw their attention to them. In practice, that is too ambitious.
-One real example: a change in the file layout of an installed GHC inadvertently broke a
-downstream distribution which happened to rely on the previous layout.
-
-Our plan is what you would expect: try to be aware of the
-impact of changes made during development and gather feedback on issues in a
-timely fashion. Eventually make a candidate release, invite downstream users to
-try it out and be receptive to their feedback.
-
-We discussed three modes of communications: 
-
-1. **Proactive status email(s)** from GHC developers to a specified list of consumers,
-   explaining the release schedule, saying (so far as possible) what is
-   changing, inviting feedback (e.g. [the GHC 9.12.1 status update](https://mail.haskell.org/pipermail/ghc-releases/2024-November/000030.html)).
-   Such active communications should be expected on major developments in the
-   release process. This is a form of "push" communication.
-
-2. **A shared channel**, devoted to releases, that allows release consumers to
-   chat informally with each other and with the release manager.
-
-   This is a form of "opt-in" communication, and does not replace (1)!
-   Proactive emails (1) should be cc'd to the shared channel, but we should not
-   rely on downstream consumers constantly monitoring the shared channel.  
-
-3. **Occassional meetings** where stakeholders can debrief previous releases, plan future
-   releases, and generally discuss.
+In all communications we hold ourselves to the [Haskell Foundation Guidelines
+for Respectful Communications][GRC]. We hope and expect that our counterparts
+will similarly follow these guidelines.
 
-In all communications we will strive to treat with other with respect and courtesy.
+[GRC]: https://haskell.foundation/guidelines-for-respectful-communication/
 
 ## 3.1 Terminology
 
-- 
GitLab


From 1ecbdf5e031ffc68cf1917e897652e79ad69b891 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Tue, 21 Jan 2025 17:57:51 -0500
Subject: [PATCH 09/20] rel-mgmt: Fix section numbering

---
 release-management.mkd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 76b1d8e..21c0061 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -251,7 +251,7 @@ GHC developers use the following communications channels:
 [haskell-releases]: https://app.element.io/?updated=1.11.19#/room/#haskell-releases:matrix.org
 
 
-## 4.3 Communications for major releases of GHC
+## 3.3 Communications for major releases of GHC
 
 The status of major GHC releases will be communicated as follows:
 
@@ -278,7 +278,7 @@ The status of major GHC releases will be communicated as follows:
 
 [ghc-status]: https://gitlab.haskell.org/ghc/ghc/-/wikis/GHC-Status
 
-## 4.4 Patch-level (aka minor) releases of GHC
+## 3.4 Patch-level (aka minor) releases of GHC
 
 Even for patch-level releases, following the process of announcing a release
 candidate, with two weeks to try it out, is good practice.
-- 
GitLab


From 4d135c18ec18e1726d7b34b67cd64957e033c9eb Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@well-typed.com>
Date: Tue, 18 Feb 2025 23:10:01 +0000
Subject: [PATCH 10/20] Apply 1 suggestion(s) to 1 file(s)

Co-authored-by: Adam Gundry <adam@well-typed.com>
---
 release-management.mkd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/release-management.mkd b/release-management.mkd
index 21c0061..c094d7f 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -7,7 +7,7 @@ authors:
  - Julian Ospald
 ---
 
-These notes summarise a discussion to improve GHC's release processes,
+These notes describe the policy for GHC's release processes,
 especially concerning the partnership between
 
 * "upstream producers": those producing GHC's releases (roughly: the GHC team), and
-- 
GitLab


From adf4d0496ae61fe7dfd48b5509475744b34d1baf Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@well-typed.com>
Date: Fri, 4 Apr 2025 12:30:44 +0000
Subject: [PATCH 11/20] Apply 1 suggestion(s) to 1 file(s)

---
 release-management.mkd | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index c094d7f..dae067d 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -115,9 +115,13 @@ The GHC and GHCup teams will take an active role in providing releases via GHCup
 
 * Official GHC releases and prereleases will be made available by the release
   manager via GHCup's `vanilla` and `prerelease` channels, respectively
-* The aspiration is that, for tier 1 platforms, a GHC release (shipped in the
+* GHC HQ's aspiration is that, for tier 1 platforms, a GHC release (shipped in the
   GHCup `vanilla` channel) is of high enough quality to be a quality-assured
-  release (shipped in the GHCup `default` channel) without patches.  
+  release (shipped in the GHCup `default` channel) without patches. 
+* However, in some cases downstreams may find a need to apply patches to the
+  source distribution pre-compilation (known here as "patching") or alter built
+  binary distributions post-compilation (known here as "repackaging"). In this
+  case:
   * If a downstream should need to repackage of release artifacts they are
     asked to consult with upstream such that the underlying issue can be
     addressed
-- 
GitLab


From 882276f44a977cb6ab5504c2228789fc2e749c49 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Fri, 4 Apr 2025 08:34:52 -0400
Subject: [PATCH 12/20] More phrasing changes

---
 release-management.mkd | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 21c0061..2d8ec37 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -84,7 +84,7 @@ to its wide adoption and close involvement with GHC upstream.
   * The user’s guide, manual page (where applicable) and Haddock documentation
     for GHC and boot libraries must build  
   * No such guarantees are provided for Tier 2 or lower platforms  
-* Haddock documentation for GHC-maintained packages (e.g. `base`,
+* Haddock documentation for packages maintained by the GHC developers (e.g. `base`,
   `template-haskell`, the `ghc` library, `ghc-internal`, `ghc-prim`) is
   available on Hackage on the day of release and is fully functional.  
 * Binary distributions provided for tier 1 platforms consistently include a minimum set
@@ -118,10 +118,14 @@ The GHC and GHCup teams will take an active role in providing releases via GHCup
 * The aspiration is that, for tier 1 platforms, a GHC release (shipped in the
   GHCup `vanilla` channel) is of high enough quality to be a quality-assured
   release (shipped in the GHCup `default` channel) without patches.  
-  * If a downstream should need to repackage of release artifacts they are
-    asked to consult with upstream such that the underlying issue can be
+  * If a downstream should need to repackage release artifacts they are
+    asked to info upstream such that the underlying issue can be
     addressed
-  * When a downstream packager needs to repackage a release, the steps should
+  * When patching or repackaging involves substantive behavior changes in the compiler
+    or libraries, downstreams are encouraged to consult with GHC HQ
+    such that (a) upstream may better understand the implications of the change,
+    and (b) upstream may draw attention to unintended consequences.
+  * When a downstream packager needs to patch or repackage a release, the steps should
     be documented, reproducible, and clearly visible to end-users such that
     issues that may stem from the modifications can be readily identified by
     upstream
@@ -161,13 +165,13 @@ summarized on the [GHC wiki][library-versions].
     must provide the CLC sufficient time (at least two weeks) to consider and
     approve the proposal.
 
-* Boot library maintainers should provide Hackage releases and version control
-  tags in a timely manner  
+* GHC HQ recommends that boot library maintainers provide Hackage releases and
+  version control tags in a timely manner  
 
-* Boot library maintainers should notify GHC before increasing their dependency
-  footprint (including package)  
+* Boot library maintainers are encouraged to notify GHC HQ before increasing
+  their dependency footprint
 
-* GHC upstream expects that boot library maintainers make conditional or
+* GHC upstream encourages boot library maintainers to make conditional or
   otherwise avoid unnecessary use of `TemplateHaskell` as such usage poses a
   challenge for bootstrapping and cross-compiling GHC
 
@@ -198,8 +202,8 @@ When considering communications modes, it is helpful to distinguish:
     example by subscribing to an email list or reading the Haskell Discourse
 
 In all communications we hold ourselves to the [Haskell Foundation Guidelines
-for Respectful Communications][GRC]. We hope and expect that our counterparts
-will similarly follow these guidelines.
+for Respectful Communications][GRC]. We encourage our counterparts
+to similarly follow these guidelines.
 
 [GRC]: https://haskell.foundation/guidelines-for-respectful-communication/
 
-- 
GitLab


From 619c37f6becd91d3041661585c0a7b34bcecba07 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Fri, 4 Apr 2025 08:38:17 -0400
Subject: [PATCH 13/20] Undo revert

---
 release-management.mkd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/release-management.mkd b/release-management.mkd
index f9793cc..1be36be 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -123,7 +123,7 @@ The GHC and GHCup teams will take an active role in providing releases via GHCup
   binary distributions post-compilation (known here as "repackaging"). In this
   case:
   * If a downstream should need to repackage of release artifacts they are
-    asked to consult with upstream such that the underlying issue can be
+    asked to info upstream such that the underlying issue can be
     addressed
   * When patching or repackaging involves substantive behavior changes in the compiler
     or libraries, downstreams are encouraged to consult with GHC HQ
-- 
GitLab


From 5e6a67c03742937afe8c6b8c55de330ea9ce3f18 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Fri, 4 Apr 2025 08:39:27 -0400
Subject: [PATCH 14/20] Recognize patch/repackage distinction

---
 release-management.mkd | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/release-management.mkd b/release-management.mkd
index 1be36be..e8f2ab8 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -132,7 +132,10 @@ The GHC and GHCup teams will take an active role in providing releases via GHCup
   * When a downstream packager needs to patch or repackage a release, the steps should
     be documented, reproducible, and clearly visible to end-users such that
     issues that may stem from the modifications can be readily identified by
-    upstream
+    upstream.
+  * If the distributor applies patches which only affect binary artifacts
+    then we ask that the applied patches are made available to aid in later
+    issue characterisation.
   * Binary distributions provided for non-tier-1 platforms should be clearly marked to users  
 
 [platform-tiers]: https://gitlab.haskell.org/ghc/ghc/-/wikis/platforms
-- 
GitLab


From c30e5dfe1c0b20e3ecfa50cb6dd6f175941f477b Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Fri, 4 Apr 2025 08:40:25 -0400
Subject: [PATCH 15/20] Clarify PVP bump restriction

---
 release-management.mkd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/release-management.mkd b/release-management.mkd
index e8f2ab8..1b81ca2 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -161,7 +161,7 @@ summarized on the [GHC wiki][library-versions].
   window (2 to 3 weeks) for the maintainer to recommend alternative versions.
 
 * Proposal coordination with the core libraries committee (CLC):
-  * Changes to the interfaces of `base`, `template-haskell`, and other core
+  * Major PVP version bumps to `base`, `template-haskell`, and other core
     libraries under GHC control should not be made in minor releases.
     Exceptions may be made for security vulnerabilities and severe correctness
     issues.
-- 
GitLab


From 0b5e1d5942996f9d715abdc68c5b0177fff8a20f Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Fri, 4 Apr 2025 08:40:53 -0400
Subject: [PATCH 16/20] Drop CLC timeframe

---
 release-management.mkd | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 1b81ca2..90621c7 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -169,8 +169,7 @@ summarized on the [GHC wiki][library-versions].
     and merged before a release branch is forked. Among other things this
     ensures that `Cabal` can support any added pragmas.
   * If the GHC Team intends to include a CLC proposal in a GHC release they
-    must provide the CLC sufficient time (at least two weeks) to consider and
-    approve the proposal.
+    must provide the CLC sufficient time to consider and approve the proposal.
 
 * GHC HQ recommends that boot library maintainers provide Hackage releases and
   version control tags in a timely manner  
-- 
GitLab


From cab0e67e5eaacdee6ef6b575c2b8cea0c61f8181 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Fri, 4 Apr 2025 09:49:13 -0400
Subject: [PATCH 17/20] clarify bootstrapping compatibility

---
 release-management.mkd | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 90621c7..cecbb4d 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -78,9 +78,13 @@ to its wide adoption and close involvement with GHC upstream.
   candidate and the final release will be provided
 * GHC will clearly document which platforms are supported by each release according to the
   established [platform tier classification][platform-tiers]
+* Each GHC version supports bootstrapping from the latest two major GHC releases. That is, GHC $x.y.z$
+  may be bootstrapped using GHC $x.(y-1).z'$ or $x.(y-2).z''$ where $z'$ and $z''$ are the latest
+  releases in their respective major series.
 * Starting from a source distribution tarball, on all tier 1 platforms:
 
-  * GHC itself, including all of its boot libraries, must build to produce a functional compiler  
+  * GHC itself, including all of its boot libraries, must build to produce a functional compiler
+    when bootstrapped with one of the supported boostrap compilers
   * The user’s guide, manual page (where applicable) and Haddock documentation
     for GHC and boot libraries must build  
   * No such guarantees are provided for Tier 2 or lower platforms  
@@ -94,7 +98,7 @@ to its wide adoption and close involvement with GHC upstream.
   * HTML users guide
   * Haddocks  
   * profiling and vanilla libraries  
-  * Hadrian bootstrap sources for the latest minor GHC releases of the last three major release series
+  * Hadrian bootstrap sources for each of the supported bootstrap compilers
 
   Note that certain characteristics of bindists are inherently different
   between platforms (e.g. static vs dynamic linkage, `libffi`, `gmp`, `libc`
-- 
GitLab


From 442662379377fb2e942ebc2a9ff272f32c6581ac Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Fri, 4 Apr 2025 09:54:20 -0400
Subject: [PATCH 18/20] Lengthen testing period of x.y.1 releases

---
 release-management.mkd | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/release-management.mkd b/release-management.mkd
index cecbb4d..536ea8c 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -286,7 +286,7 @@ The status of major GHC releases will be communicated as follows:
 1. When a release candidate comes out: email to <ghc-releases@haskell.org> inviting action:
   * Invite downstream users to take it for a test drive  
   * There will be at least a two-week window between the release candidate and
-    final release for testing and feedback
+    final release for testing and feedback. This will be lengthened to four weeks for $x.y.1$ releases.
   * This step may be repeated if substantial changes are made, albeit perhaps
     with a shorter response window.
 
-- 
GitLab


From b876ff0ef50329e669a8b99d0edabc32f6b049a7 Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Fri, 4 Apr 2025 11:06:31 -0400
Subject: [PATCH 19/20] Formatting consistency

---
 release-management.mkd | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index 536ea8c..ae20678 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -312,7 +312,8 @@ release.
 
 Beyond releases, if GHC HQ decides to make major changes in platform or
 architecture support, they should inform the community well in advance, at
-least by email to `ghc-devs@`, to `ghc-releases@`, and a Discourse post.  
+least by email to <ghc-devs@haskell.org>, to <ghc-releases@haskell.org>, and a
+Discourse post.  
 
 Examples of such announcements include:
 
@@ -325,16 +326,16 @@ Examples of such announcements include:
     directly if we know they might be affected.
 
 * **Major changes to how GHC is compiled from source** are communicated to
-  users via [ghc-releases@haskell.org](mailto:ghc-releases@haskell.org) and the
+  users via <ghc-releases@haskell.org> and the
   release notes
 
 * **Bindist changes**:  
   * Significant changes to the top level file layout of installed bindists are
-    communicated to downstream users via ghc-releases@haskell.org  
+    communicated to downstream users via <ghc-releases@haskell.org>
   * Significant changes to the user-facing installation procedure (e.g.
-    \`configure\` and \`make install\`) are communicated to users via the
+    `configure` and `make install`) are communicated to users via the
     release notes and the release announcement.  
-  * Big changes to windows toolchains e.g. switching from gcc to clang are
-    communicated via ghc-releases@haskell.org. Smaller changes like upgrades to
+  * Big changes to windows toolchains e.g. switching from `gcc` to `clang` are
+    communicated via <ghc-releases@haskell.org>. Smaller changes like upgrades to
     the shipped versions are documented in release notes.
 
-- 
GitLab


From 07da84cdf2b270f555192606999648b25cbb42ef Mon Sep 17 00:00:00 2001
From: Ben Gamari <ben@smart-cactus.org>
Date: Fri, 4 Apr 2025 11:09:34 -0400
Subject: [PATCH 20/20] Drop "top level"

---
 release-management.mkd | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/release-management.mkd b/release-management.mkd
index ae20678..c9346b8 100644
--- a/release-management.mkd
+++ b/release-management.mkd
@@ -327,10 +327,10 @@ Examples of such announcements include:
 
 * **Major changes to how GHC is compiled from source** are communicated to
   users via <ghc-releases@haskell.org> and the
-  release notes
+  release notes.
 
 * **Bindist changes**:  
-  * Significant changes to the top level file layout of installed bindists are
+  * Significant changes to the file layout of installed bindists are
     communicated to downstream users via <ghc-releases@haskell.org>
   * Significant changes to the user-facing installation procedure (e.g.
     `configure` and `make install`) are communicated to users via the
-- 
GitLab