3.12 changelog fixup (#9922)

* Incorporate Brandon’s suggestions See #9920. * Incorporate Artem’s suggestions See #9920. * Do not repeat yourself
haskell · Apr 23, 2024 · 9c63caa · 9c63caa
1 parent f687159
commit 9c63caa
Show file tree

Hide file tree

Showing 2 changed files with 54 additions and 55 deletions.
diff --git a/release-notes/Cabal-3.12.0.0.md b/release-notes/Cabal-3.12.0.0.md
@@ -38,7 +38,7 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
     build the package. This allows us to configure all the packages we intend
     to load into the repl without building any dependenices which we will load
     in the same session, because the promise is satisifed due to loading the
-    package and it's dependency into one multi-session which ensures the
+    package and its dependency into one multi-session which ensures the
     dependency is built before it is needed.
 
     A user of ./Setup configure specifies a promised dependency by using the
@@ -73,12 +73,6 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
     This library was only used by internal tests, and now lives in the
     `Cabal-tests` library which is shared across test components.
 
-- Distinguish `powerpc64le`, by adding `PPC64LE` constructor to type `Arch` [#9534](https://github.com/haskell/cabal/issues/9534) [#9535](https://github.com/haskell/cabal/pull/9535)
-
-    Adds constructor `PPC64LE` to type `Arch` to distinguish architecture
-    powerpc64le from powerpc64. Existing constructor `PPC64` now exclusively
-    represents powerpc64.
-
 - PkgConfig individual calls [#9134](https://github.com/haskell/cabal/pull/9134)
 
     `cabal` invokes `pkg-config` individually for each lib if querying for all
@@ -118,7 +112,7 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
     the repl and instead instruct the command to write the necessary build
     flags to a directiory. The option is called `--repl-multi-file <DIR>`.
 
-    This is useful when starting multi-component sessions as we want to query
+    This is useful when starting multi-component sessions, as we want to query
     Setup.hs for the arguments which are needed to build each component but
     not for ./Setup to start the repl itself.
 
@@ -169,12 +163,19 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
     to decide whether to allow or discard such inexact matches.
 
 - Document `remote-repo-cache` as implemented. [#8737](https://github.com/haskell/cabal/issues/8737) [#8738](https://github.com/haskell/cabal/pull/8738)
+
 - Deduplicate LD_LIBRARY_PATH when running tests [#8728](https://github.com/haskell/cabal/pull/8728)
-- Add support for the 64-bit RISC-V architecture [#9062](https://github.com/haskell/cabal/pull/9062)
-- Add support for 64-bit LoongArch architecture [#9215](https://github.com/haskell/cabal/pull/9215)
+
+- Add support for a number of architectures:
+
+    - RISC-V [#9062](https://github.com/haskell/cabal/pull/9062)
+    - 64-bit LoongArch [#9215](https://github.com/haskell/cabal/pull/9215)
+    - 64-bit SPARC as a separate architecture [#9445](https://github.com/haskell/cabal/pull/9445)
+
 - Don't report `index.html` file as created, if not created by Haddock [#5120](https://github.com/haskell/cabal/issues/5120) [#9332](https://github.com/haskell/cabal/pull/9332)
+
 - Enable using $ORIGIN in RPATH on GNU/Hurd [#9441](https://github.com/haskell/cabal/pull/9441)
-- Add support for 64-bit SPARC as a separate architecture [#9445](https://github.com/haskell/cabal/pull/9445)
+
 
 - Make check comply with Hackage requirements [#8897](https://github.com/haskell/cabal/pull/8897)
 
@@ -185,9 +186,9 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
     third-party tools to know if a specific error will preclude a package
     from being uploaded to Hacakge.
 
-- Add language extension ExtendedLiterals [#8992](https://github.com/haskell/cabal/pull/8992)
+- Add language extension `ExtendedLiterals` [#8992](https://github.com/haskell/cabal/pull/8992)
 
-    Adds support for the ExtendedLiterals language extension (GHC proposal #451)
+    Adds support for the `ExtendedLiterals` language extension (GHC proposal #451)
 
 - Warn about inconsistent indentation [#8975](https://github.com/haskell/cabal/pull/8975)
 
@@ -212,19 +213,19 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
     Such insonsistency seems to be always a mistake, and it's easy to fix once
     a machine points it out.
 
-- Add LexBraces lexer warning [#8577](https://github.com/haskell/cabal/issues/8577)
+- Add `LexBraces` lexer warning [#8577](https://github.com/haskell/cabal/issues/8577)
 
-    LexBraces warning is issued when brace delimiting syntax is used.  This
+    `LexBraces` warning is issued when brace delimiting syntax is used.  This
     way, using `readFields'`, a low-lever consumer may decide whether braces
     were used.
 
-    (Looking for a brace character in the input is imprecise, as braces can
-    occur inside field content).
+    Looking for a brace character in the input is imprecise, as braces can
+    occur inside field content.
 
     This warning is not propagated to parser warnings, so e.g.
-    readGenericPackageDescription doesn't warn about it.  This is because all
+    `readGenericPackageDescription` doesn't warn about it.  This is because all
     parser warnings prevent uploads to Hackage, and using braces (or not) is
-    opinionated choice.
+    a matter of opinion.
 
 - Distinguish `powerpc64le`, by adding `PPC64LE` constructor to type `Arch` [#9534](https://github.com/haskell/cabal/issues/9534) [#9535](https://github.com/haskell/cabal/pull/9535)
 
@@ -236,7 +237,7 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
 
     `cabal` invokes `pkg-config` individually for each lib if querying for all doesn't return the expected result
 
-- Add language extension ListTuplePuns [#8854](https://github.com/haskell/cabal/pull/8854)
+- Add language extension `ListTuplePuns` [#8854](https://github.com/haskell/cabal/pull/8854)
 
     Adds support for the `ListTuplePuns` language extension (GHC proposal #475)
 
@@ -248,10 +249,6 @@ Cabal and Cabal-syntax 3.12.0.0 changelog and release notes
 
 - Add language extension `TypeAbstractions` [#9496](https://github.com/haskell/cabal/issues/9496) [#9502](https://github.com/haskell/cabal/pull/9502)
 
-- Add support for the 64-bit RISC-V architecture [#9062](https://github.com/haskell/cabal/pull/9062)
-- Add support for 64-bit LoongArch architecture [#9215](https://github.com/haskell/cabal/pull/9215)
-- Add support for 64-bit SPARC as a separate architecture [#9445](https://github.com/haskell/cabal/pull/9445)
-
 - Update SPDX License List to version `3.23 2024-02-08` [#9818](https://github.com/haskell/cabal/pull/9818)
 
   - LicenseId and LicenseExceptionId now conform to SPDX License List

diff --git a/release-notes/WIP-cabal-install-3.12.x.0.md b/release-notes/WIP-cabal-install-3.12.x.0.md
@@ -3,10 +3,10 @@
 cabal-install and cabal-install-solver 3.12.1.0 changelog and release notes
 ---
 
-- Add --project-dir flag [#7695](https://github.com/haskell/cabal/issues/7695) [#7940](https://github.com/haskell/cabal/issues/7940) [#8454](https://github.com/haskell/cabal/pull/8454)
+- Add `--project-dir` flag [#7695](https://github.com/haskell/cabal/issues/7695) [#7940](https://github.com/haskell/cabal/issues/7940) [#8454](https://github.com/haskell/cabal/pull/8454)
 
-    - Added --project-dir flag for specifying the project's root directory
-    - Deprecated using --project-file with an absolute filepath without also using --project-dir
+    - Added `--project-dir` flag for specifying the project's root directory
+    - Deprecated using `--project-file` with an absolute filepath without also using `--project-dir`.
 
 - Remove useles "Log" log level [#9151](https://github.com/haskell/cabal/issues/9151) [#9346](https://github.com/haskell/cabal/pull/9346)
 
@@ -32,7 +32,7 @@ cabal-install and cabal-install-solver 3.12.1.0 changelog and release notes
     a flag which specifies which libraries should be included in the coverage
     report for some testsuite.
 
-- Redesign 'cabal path' command to account for projects [#9673](https://github.com/haskell/cabal/pull/9673)
+- Redesign `cabal path` command to account for projects [#9673](https://github.com/haskell/cabal/pull/9673)
 
   Previously, `cabal path` was only able to query from the global configuration file, e.g., `~/.cabal/config` or the XDG equivalent.
   We take the foundations and enhance `cabal path` to take project configuration, such as `cabal.project`, into account.
@@ -55,11 +55,27 @@ cabal-install and cabal-install-solver 3.12.1.0 changelog and release notes
   To do that, we re-configure the compiler program, and outputs the location, version and compiler flavour.
   This is helpful for downstream tools, such as HLS, to figure out the GHC version required to compile a project with, without dependency solving.
 
+- Add support for authentication tokens for uploading to Hackage [#6738](https://github.com/haskell/cabal/issues/6738) [#9058](https://github.com/haskell/cabal/pull/9058)
+
+    A new flag `--token` (`-t`) has been created. Token authentication takes 
+    precedence over username and password meaning that, if a token is set, 
+    the username and password flags are ignored.
+
+- Make --(test-)show-details=direct the default [#8942](https://github.com/haskell/cabal/pull/8942)
+
+    This option leaves it up to the testing framework to decide what and how to print out,
+    potentially leading to a prettier output. For example, most of the testing frameworks
+    use colors, which wouldn't be seen with any other option.
+
+    This comes with a tradeoff, though: Cabal will not create a log file with this option.
+    If you prefer a log file, consider setting `--test-show-details=streaming` (or something
+    else) manually.
+
 ### Other changes
 
 - Script cache dir is the base16 hash of the canonical path of the script. [#9459](https://github.com/haskell/cabal/pull/9459)
 
-    Script cache dir is the base16 hash of the canonical path of the script.
+    This fixes sporadic path failures on both Windows and Linux (e.g. [#9334](https://github.com/haskell/cabal/issues/9334)).
 
 - Die if package list is missing [#8944](https://github.com/haskell/cabal/pull/8944)
 
@@ -83,22 +99,6 @@ cabal-install and cabal-install-solver 3.12.1.0 changelog and release notes
     before the build, that an overwrite policy flag would be needed for the
     install to succeed.
 
-- Add support for authentication tokens for uploading to Hackage [#6738](https://github.com/haskell/cabal/issues/6738) [#9058](https://github.com/haskell/cabal/pull/9058)
-
-    A new flag `--token` (`-t`) has been created. Token authentication takes 
-    precedence over username and password meaning that, if a token is set, 
-    the username and password flags are ignored.
-
-- Make --(test-)show-details=direct the default [#8942](https://github.com/haskell/cabal/pull/8942)
-
-    This option leaves it up to the testing framework to decide what and how to print out,
-    potentially leading to a prettier output. For example, most of the testing frameworks
-    use colors, which wouldn't be seen with any other option.
-
-    This comes with a tradeoff, though: Cabal will not create a log file with this option.
-    If you prefer a log file, consider setting `--test-show-details=streaming` (or something
-    else) manually.
-
 - Make sure Haskell files in explicit source directories take precedence over autogenerated Haskell files [#8689](https://github.com/haskell/cabal/issues/8689) [#8690](https://github.com/haskell/cabal/pull/8690)
 
     - Changed order or directories in GHC invocation so that source
@@ -127,13 +127,13 @@ cabal-install and cabal-install-solver 3.12.1.0 changelog and release notes
     name did not match exactly. Now they will be cached even if the header's
     capitalization is different.
 
-- Clarify the semantics of the -package-db flag [#9678](https://github.com/haskell/cabal/issues/9678)
+- Clarify the semantics of the `--package-db` flag [#9678](https://github.com/haskell/cabal/issues/9678)
 
     The `--package-db` flag now only applies to the default
     immutable initial package stack rather than also applying to the store
     package database.
 
-    This fixes an assertion failure which was triggered when using -package-db and also
+    This fixes an assertion failure which was triggered when using `--package-db` and also
     clarifies how it should interact with `--store-dir` and `--dist-dir` flags.
 
 - PkgConfig individual calls [#9134](https://github.com/haskell/cabal/pull/9134)
@@ -212,14 +212,14 @@ cabal-install and cabal-install-solver 3.12.1.0 changelog and release notes
     cabal-install would silently ignore them. Now cabal-install will emit a
     warning.
 
-- Fix precedence for PATH for build-tools-depends [#8972](https://github.com/haskell/cabal/pull/8972)
+- Fix precedence for PATH for `build-tools-depends` [#8972](https://github.com/haskell/cabal/pull/8972)
 
     Fixes a bug introduced in #8506 that caused executables in the path to
-    take precedence over those specified in build-tools-depends.
+    take precedence over those specified in `build-tools-depends`.
 
-- Remove --cabal-file flags from v2 commands [#6880](https://github.com/haskell/cabal/issues/6880) [#7225](https://github.com/haskell/cabal/issues/7225) [#8395](https://github.com/haskell/cabal/issues/8395) [#9123](https://github.com/haskell/cabal/pull/9123)
+- Remove `--cabal-file` flags from v2 commands [#6880](https://github.com/haskell/cabal/issues/6880) [#7225](https://github.com/haskell/cabal/issues/7225) [#8395](https://github.com/haskell/cabal/issues/8395) [#9123](https://github.com/haskell/cabal/pull/9123)
 
-    The --cabal-file flag was never meant for public use but only for testing.
+    The `--cabal-file` flag was never meant for public use but only for testing.
     To avoid confusing the users any further we removed the flag from v2
     commands.
 
@@ -228,16 +228,19 @@ cabal-install and cabal-install-solver 3.12.1.0 changelog and release notes
     The "Executing·install·plan··serially" and other similar "Executing
     install plan··..." outputs no longer contain double spaces.
 
-- Guard PackageInfo_* modules behind `cabal-version` ≥ 3.12 [#9331](https://github.com/haskell/cabal/issues/9331) [#9481](https://github.com/haskell/cabal/pull/9481)
+- Guard `PackageInfo_*` modules behind `cabal-version` ≥ 3.12 [#9331](https://github.com/haskell/cabal/issues/9331) [#9481](https://github.com/haskell/cabal/pull/9481)
 
-    `cabal check` now warns whenever PackageInfo_* autogen modules are
+    `cabal check` now warns whenever `PackageInfo_*` autogen modules are
     used with `cabal-version` ≥ 3.12.
-    Additionally, `cabal configure` will fail if you try to use PackageInfo_*
+    Additionally, `cabal configure` will fail if you try to use `PackageInfo_*`
     with `cabal-version` < 3.12.
 
 - cabal init now generates cabal versions older than 1.12 with the correct >= syntax [#8206](https://github.com/haskell/cabal/issues/8206) [#8860](https://github.com/haskell/cabal/pull/8860)
+
 - `cabal init`: suggest BSD-3 as default license [#8757](https://github.com/haskell/cabal/issues/8757) [#8764](https://github.com/haskell/cabal/pull/8764)
+
 - Do not ask overwrite permissions on blank project [#9150](https://github.com/haskell/cabal/issues/9150) [#9155](https://github.com/haskell/cabal/pull/9155)
+
 - Don't report `index.html` file as created, if not created by Haddock [#5120](https://github.com/haskell/cabal/issues/5120) [#9332](https://github.com/haskell/cabal/pull/9332)
 
 - Shorten solver rejection messages by removing repetition [#4251](https://github.com/haskell/cabal/issues/4251) [#9559](https://github.com/haskell/cabal/issues/9559) [#9560](https://github.com/haskell/cabal/pull/9560)
@@ -284,4 +287,3 @@ cabal-install and cabal-install-solver 3.12.1.0 changelog and release notes
   This change matters to BSD-2-Clause and BSD-3-Clause licences. For these two
   licences, `cabal init` created a licence file that slightly differed from
   wording published at SPDX.  This has been rectified.
-