Custom-build: Document breaking change on built comps.

[alt-romes]

As mentioned by e8c9d19, Cabal 3.12 introduced a breaking change where an unnecessary (not requested) component of a package with a "Custom" build-type is no longer built.

This caused breakage for Agda, and was undocumented.

The behaviour, despite breaking, is the desired one -- a package shouldn't assume the executable will be built if only the library was requested. This commit documents the breaking change to make sure it is more visible.

• Patch Agda to no longer expect the executable to be built when only the library is installed.

Closes #9777 and #10235

Please read Github PR Conventions and then fill in one of these two templates.

---

Template Α: This PR modifies behaviour or interface

Include the following checklist in your PR:

• Patches conform to the coding conventions.
• Any changes that could be relevant to users have been recorded in the changelog.
• The documentation has been updated, if necessary.
• Manual QA notes have been included.
• Tests have been added. (Ask for help if you don’t know how to write them! Ask for an exemption if tests are too complex for too little coverage!)

[geekosaur]

Do we also want to make sure the manual is clear on this?

[alt-romes]

I've pushed the patch to Agda that updates its Setup script to account for this new behaviour in agda/agda#7471.

[fgaz]

Looks good. I think we can skip the changelog.d entry and add this directly to the changelog.

[fgaz]

Maybe add #9650

[alt-romes]

Okay. what does it mean to skip the changelog entry? do you want me to add this to the changelog right away?

[alt-romes]

I thought the changelog was generated programatically from the entries

[fgaz]

what does it mean to skip the changelog entry? do you want me to add this to the changelog right away?

yes please. you can generate the markdown with https://codeberg.org/fgaz/changelog-d

I thought the changelog was generated programatically from the entries

It is, but we mostly do that to avoid merge conflicts, which shouldn't be a concern in this case. Also now there are only >=3.14 entries in changelog.d/, and we don't want to mix them up.

[ulysses4ever]

I agree with Francesco that at this point it's too late to go via changelog-files, and one of the release-notes documents should be adjusted retroactively. Not sure 3.12.0.0 or 3.12.0.1: need to double-check with the git history.

[geekosaur]

The Hackage changelogs just point to the changelog files on master.

[alt-romes]

Got it. This is ready then, please take a look again.

[philderbeast]

The Hackage changelogs just point to the changelog files on master.

With the changelog files compiled as release notes being markdown, they're easily publishable elsewhere too as I'm doing here with an update for Cabal's own website, (as an update to https://www.haskell.org/cabal/).

https://discourse.haskell.org/t/hakyll-is-awesome/9838
https://cabal.blockscope.com/releases/

[Mikolaj]

The ability to hotfix the release notes is soo convenient. But we are not overusing it and the notes/changelogs pertain to one release only (and we never modify any but the last one, I think), so snapshots of our release notes shall never get too outdated. Maybe we should state somewhere clearly that the only authoritative source of the changelog is the master branch in the repo. But linking to a file in a moving branch quite clearly indicates that, doesn't it?

[geekosaur]

I think what might be more helpful is documentation that we do this and why. In particular, I personally found the indirection in the Hackage changelogs annoying at first, especially given that if you read on you find older actual changelogs. This would be a fixed preamble in the changelog files.