Define a user-visible change

[philderbeast]

In support of #9944, define what a user-visible change is in CONTRIBUTING.md.

• Patches conform to the coding conventions.
• Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions).

[ffaf1]

Do you think you can make this a subsection? So we can directly link to this?

[philderbeast]

@ffaf1 would an anchor suffice?

https://github.com/cabalism/cabal/blob/docs/user-visible-is/CONTRIBUTING.md#user-visible-change

[ffaf1]

Firefox 115 mangles it (goes a few lines too far)

[philderbeast]

Dang, Firefox 125.0.2 on ubuntu does fine with it and the same as chromium, bringing the whole sentence into view at the top of the frame with the anchor underlined.

[geekosaur]

Same with Chrome 124.0.6367.91 (works fine).

[ffaf1]

If it is the first paragraph in that section, a link to #changelog will be fine!

[philderbeast]

Here's a link to the #changelog anchor;

https://github.com/cabalism/cabal/blob/docs/user-visible-is/CONTRIBUTING.md#changelog

[ffaf1]

Very good!

[philderbeast]

Label merge+no rebase is necessary when the pull request is from an organisation.

[Mikolaj]

It's just been pointed out to me in #9952 (comment) that dropping support of a GHC version (by removing it from CI, which should be accompanied by revising a base bound) is a crucial change for some users. Could we incorporate that one into the needs-changelog guideline (maybe directly into the user-visible definition?)?

[ffaf1]

Could we incorporate that one into the needs-changelog guideline (maybe directly into the user-visible definition?)?

I put this in the “Making a release document”, do you feel it is better to have it there (one-off activity every nine months) or here (instruction to each PR). I am OK in any case.

[philderbeast]

It's just been pointed out to me in #9952 (comment) that dropping support of a GHC version (by removing it from CI, which should be accompanied by revising a base bound) is a crucial change for some users. Could we incorporate that one into the needs-changelog guideline (maybe directly into the user-visible definition?)?

@Mikolaj I've added something about this;

Raising the lower bound on base is most definitely a user-visible change because it
excludes versions of GHC from being able to build these packages.

[Mikolaj]

LGTM

[Mikolaj]

@philderbeast: thank you

@ffaf1: I'm lazy so I'd rather PR authors do all the work in the chagelog files. However, the recent experience shows we need to monitor that PRs get proper changelogs, so IMHO this bit also makes sense in the major release checklist (especially that it's rather cheap to compare CI scripts and base bounds with what was there in the previous major release, as opposed to going through all PRs and verifying they don't break API silently).

[ffaf1]

so be it, then let’s update it here and I will slightly reword “Making a release”.

[Mikolaj]

I don't think we need to backport that one.