Release checklist for `3.18.2.0` (minor release)

[ffaf1]

Release manager: @ffaf1
Join Matrix to help with the release!

Feel free to modify the layout or add your comments.

Important/urgent open problems

Comments welcome:

• We would like to release cabal-install only, but Fix renameFileWithRetry leaving temporary files after copying #12246, which is the main fix we would like to release, modifies Cabal-syntax. What to do? Release everything? Land a PR in cabal-install that does not touch Cabal-syntax?
  Answer: I guess we will release Cabal-syntax and friends too, the fix is too important.
• In cabal run stopped recognizing target name after -- with cabal-install 3.18.1.0 #12231 most likely we are not going to have our cake (pass options on empty targets) and eat it (follow POSIX guidelines). Which path should we choose?
• Build and release is broken! for FreeBSD Fix FreeBSD reusable release #12391
  • Run “Build and release” action, check that it is green.
  • backport to master Backport #12391: Fix FreeBSD reusable release #12392
  • backport to 3.18 Backport #12391: Fix FreeBSD reusable release #12393
  • axe the unused branch
• Retag 3.18
  • Fix changelogs #12400
  • Backport it Backport #12400: Fix changelogs #12401
  • Retag 3.18.2.0

Regressions

There are a number regressions we would like to take care of before releasing.

• Cabal package not visible to build auto-generated setup.hs #11416 (PR: Allow minor Cabal version bumps without recompiling #12289) 🔴 This cannot be backported, it breaks cabal-install API!
• cabal-install 3.18.1.0 leaves many .tmp files in /tmp #12244 (PR: Fix renameFileWithRetry leaving temporary files after copying #12246)
  • backport Backport #12246: Fix renameFileWithRetry leaving temporary files after copying #12298
• cabal run stopped recognizing target name after -- with cabal-install 3.18.1.0 #12231 No backport, see discussion, we keep the new behaviour and add a section to the release notes warning users.
  • Write such section for 3.18.2.0 and 3.18.1.0.
• cabal-install 3.18.1.0 project file incorrect configure-options warning #12245 (PR: fix(cabal-install): Fix spurious "Unknown field: configure-options" warning #12276)
  • backport Backport #12276: fix(cabal-install): Fix spurious "Unknown field: configure-options" warning #12307
• Lock store creation against concurrent processes #12114
  • backport Backport #12114: Lock store creation against concurrent processes #12314
• cabalSpecLatest remains 3.16 in cabal-install 3.18.1.0, causing cabal-version: 3.18 Simple packages to fail #12271 Mark CabalSpecV3_18 as latest on the 3.18 branch #12273
• most likely a regression, uncontroversial windows: cabal-install built in msys-shell links against msys env specific dlls. #12272 Don't depend on zlib.dll on windows. #12274
  • backport Backport #12274: Don't depend on zlib.dll on windows. #12327
• Shallow clones break cabal.project containing same repo twice #12296 Don't use a shallow checkout as a git clone reference #11921 (QOL, simple, uncontroversial)
  • backport Backport #11921: Don't use a shallow checkout as a git clone reference #12335

There are also items, which are not a regressions, we decided (cabal-dev meeting 2026/08/27 or Francesco deciding on suggestions from cabal contributors) to include in 3.18.2.0. The reasons are because of its importance and because it slipped through the cracks in 3.18.1.0.

• cabal upload throwing curl errors #10252 (PR: Fix #10252: cabal upload fails with curl chunked-encoding error #12211)
  • backported Backport #12211: Fix #10252: cabal upload fails with curl chunked-encoding error #12297
• New token-command option for cabal upload #12132 cannot be backported 🔴 (breaks API for the library of cabal-install)
• fix(cabal-install): Honor --with-gcc and program-locations when configuring the compiler #12260
  • backport Backport #12260: fix(cabal-install): Honor --with-gcc and program-locations when configuring the compiler #12318

Other PRs/issues of note

• It is important for our users to patch 3.18.1.0 changelog
  • 3.18.1.0 changelog is misleading regarding "argument separator" #12291 (write that the old behaviour will be reintroduced) Fix 3.18.1.0 release notes #12309.
  • State “Unresolved issues and Notice” will be solved in a future release.
  • backport to master Backport #12309: Fix 3.18.1.0 release notes #12330
• Unneeded release artifacs generated by release script #12179 should be fixed before we tag the release. Remove uneeded release artifacts #12324
  • Have fix(CI): bootstrap.py no longer reuses a stale package database #12341 merged
    • backport to 3.18 Backport #12341: fix(CI): bootstrap.py no longer reuses a stale package database #12353
  • backport Backport #12324: Remove uneeded release artifacts #12338

Third-party tools concerns

(GHC, HLS, GHCup, …)

• If developers are not active in Matrix, warn them. (HLS devs already aware, GHC and GHCup devs warned.)

Checklist

Before the checklist, address:

• go through additional proposed backports, decide whether they are fit for 3.18.2.0.
  • Decide the fate of [Fix #11850] Build dependencies of build tool on disk too #12084
• Double check this is indeed a minor release
  • No API breakage.
  • No cabal file format change at all.
• go through PR discussions, check whether they need help (and get them merged)

Checklist:

• Before the release
  • Pre-flight Checks: See Preflight checks @ffaf1
  • Changelog generation: See CHANGELOGS Changelogs 3.18.2.0 #12346 @ffaf1
    • Copy “Unresolved issues and notices” from 3.18.1.0 cabal install release notes file. Erase what has been fixed.
    • backport to master Backport #12346: Changelogs 3.18.2.0 #12361
  • Bump version numbers: See Bumping version numbers Bump version numbers for 3.18.2.0 #12345 @Mikolaj
  • Tag the release: See Tagging the release (☞ N.B. Remove uneeded release artifacts #12324 has to be backported to 3.18 for this step. it was) @Mikolaj
  • Upload release candidates: See Uploading package release candidates to Hackage
  • Publish artifacts: See Publishing the artifacts
  • Publish everything else: See Publishing everything else
  • Tweak things as needed, merge patches to fix regressions
  • Re-upload the candidates on Hackage based on the latest tag, and publish them
• After the release
  • prepare a list of contributors for the release (how to do it)
  • advertise on discourse, haskell-cafe and cabal-devel and in particular (details here)
  • ask kind souls to cross-post to Mastodon, Matrix (#haskell-tooling and #haskell-language-server), Discord, Twitter, Reddit. Copy the links to #hackage so that others can upvote
  • Move the tickets that haven't made it to the release to the next one.
  • Congratulate everyone and party 🥳

[zlonast]

the typo should be:

- #11416 (PR: #12211)
+ #10252 (PR: #12211)

[zlonast]

Maybe:

• Cabal doesn’t honor program-locations gcc-locations, program-default-options ghc-options: -pgmc=, or --with-gcc #11881 (PR: fix(cabal-install): Honor --with-gcc and program-locations when configuring the compiler #12260)

[Mikolaj]

Also maybe #12084 ?

[Mikolaj]

And Artem mentions #12132

[Bodigrim]

I'd really love if we can get #12114 over the line and backport it. Otherwise HLS is painful.

[ffaf1]

Release manager journal 2026/08/30

I think the idea of releasing only cabal-install went up in the air. #12245 — the most important fix for this release — touches Cabal-syntax and #12114 too modifies Cabal. I do not see any alternative to releasing more packages.

I have added #12260, #12132, #12114 as PR of interest we would like to backport. The idea for accepting a PR is:

• it is a legitimate regression; or
• it slipped through the cracks of 3.18.1.0 and it is not likely to introduce a regression and force a further point release.

With regard to the “introduce a regression”, #12084 (suggested by @Mikolaj) has one reviewer (@fendor) stating “There is some remaining risk since I am not sure I understand the consequences entirely.” I would really love another pair of eyes on that one and HLS developers and general users to tell us how important this is and if there are workarounds and so on.

[fendor]

HLS developers

This is important to HLS and haskell-debugger as we think it is the best user experience to be able to load the whole project into the session.
For HLS, this will mean more predictable behaviour for newcomers in particular, as goto references will work out-of-the-box for the whole project, as well as the rename feature. We expect startup times to be generally better as well.

build-tool-depends on local packages currently make this workflow impossible (to generally work), it is simply broken for --enable-multi-repl. The only workaround I know of is to add a .cabal configuration disabling the build-tool-depends (e.g., flag, have a cabal.hls.project and a custom hie.yaml)

Thus, If not backported, HLS users will have to wait for the next cabal release before the glorious future :)

For haskell-debugger, it allows users to start the debugger with no further configuration and they can rely on that it will work.
Otherwise, users will have to disable build-tool-depends in the .cabal file or provide an explicit list of components to load into the debugger session (which doesn't work if the component to test is a test suite with a build-tool-depends section).

To summarise, the workaround is not viable (for the average user), the impact is medium (not everyone uses build-tool-depends) and it would be nice to have something that works at least in the average case in cabal 3.18. The testsuite doesn't break, we add a testcase for the feature we want, so I would hope that the risk is relatively small.

However, it makes sense to me to be cautious and understand if the final decision is to not backport it right now :)

[Bodigrim]

the impact is medium (not everyone uses build-tool-depends)

In practice though the chances to depend on alex or hsc2hs in a reasonably sized project are fairly high. I'd say fixing this issue is a pretty big win.

[fendor]

In practice though the chances to depend on alex or hsc2hs in a reasonably sized project are fairly high.

These build-tool-depends should be fine though, the MR and issue is solely about build-tool-depends on local components, e.g., the testsuite depends on the executable component to run the executable for integration tests.

[ffaf1]

Release manager journal 2026/09/01

Both #12289 and #12132 cannot make this release, as they modify cabal-install API.

#12231 will stay like it is now, we will just add a big warning section to the release notes (#12309).

[zlonast]

We haven't mentioned one bug here

• cabalSpecLatest remains 3.16 in cabal-install 3.18.1.0, causing cabal-version: 3.18 Simple packages to fail #12271 Mark CabalSpecV3_18 as latest on the 3.18 branch #12273

[zlonast]

I can suggest two more projects (which received moral approval from the issue authors)

• Give better error message when a global option is passed after command, not before (was "Option --config-file not recognized out of order") #7704 (PR: feat(Cabal): Give a better error message when a global option is passed after the command #12280)
• Bad error message on cabal run with multiple executable #12262 (PR: fix(cabal-install): Suggest a concrete target when cabal run matches multiple executables #12266)

[zlonast]

Milestone Considered for 3.18

Perhaps if this applies to our release, we can try merging some pull requests from here? 😅