Remove section "Bugs and Stability" from user guide

[BinderDavid]

This PR just removes the entire section "Bugs and Stability" from the users guide. It is meant as part of a larger overhaul of the structure of the cabal documentation, see #9214. Getting rid of a toplevel section that doesn't provide useful information makes it simpler to improve the discoverability of the actual useful information in the user guide.

Removing the entire section might seem radical, but it seems to me that most of the information provided in that section is outdated, wrong, vague or doesn't belong in the cabal user guide. The guarantees about the stability of the CLI interface were written before the big v1- vs v2- split, and the stability of the Custom buildtype is also in question (see https://well-typed.com/blog/2023/10/sovereign-tech-fund-invests-in-cabal/). Saying that the cabal package follows the PVP is not worth mentioning, that is obious. And I don't think people find the cabal bugtracker by searching in the user guide; nowadays you expect to find a bugtracker on Github or Gitlab.

If you find any information in that section that you think is worth being preserved, then I am happy to find a new place for it :)

[ffaf1]

Reporting bugs and deficiencies
===============================

Please report any flaws or feature requests in the `bug
tracker <https://github.com/haskell/cabal/issues>`__.

For general discussion or queries email the libraries mailing list
[email protected]. There is also a development mailing list
[email protected].

This seems useful, if obvious. MLs (and Matrix) are appropriate materials for a manual, am I wrong?

I won't comment on the "stability guarantees" paragraphs, as I don't know how stale they are.

[BinderDavid]

This seems useful, if obvious. MLs (and Matrix) are appropriate materials for a manual, am I wrong?

Yes, that information is still somewhat useful. As for the mailing lists: It doesn't seem that a lot is happening on the libraries mailing list; people use it for announcements but no discussions are happening there. And the reference to cabal-devel is more relevant for cabal developers than end users. The README in the Github repository refers to the generic Haskell Matrix channel and to the discourse forum. I will try to add that information back at the end of section 1.

I won't comment on the "stability guarantees" paragraphs, as I don't know how stale they are.

The text in that section is pretty old, it hasn't been touched since at least 2016, likely even longer than that. (2016 is when the user guide was converted to RST, and the git history of that file doesn't go back any further) Edit: I just further investigated, and the entire section was written in 2011 by Duncan Coutts, and hasn't been changed significantly since then.

[ffaf1]

Yes, that information is still somewhat useful. As for the mailing lists: It doesn't seem that a lot is happening on the libraries mailing list; people use it for announcements but no discussions are happening there. And the reference to cabal-devel is more relevant for cabal developers than end users. The README in the Github repository refers to the generic Haskell Matrix channel and to the discourse forum. I will try to add that information back at the end of section 1.

Very good, then we agree there should be a place for it in the manual? Now the question is where. Do you think adding it after “13. Nix integration” would do?

[BinderDavid]

One of the things I wanted to achieve was to reduce the number of toplevel sections (to make place for more useful ones). I think that information would fit best if we have some sort of "landing page" in the user guide, like the following: https://doc.rust-lang.org/cargo/index.html But we don't have such a section yet. I have another branch where I am rewriting a lot of the highlevel documentation, which would allow to merge the contents of the "Package concepts" and "Introduction" sections. But I am trying to propose small piecemeal changes.

What do you think about adding an unnumbered section "Welcome" at the very beginning. (I hope that unnumbered sections are possible) that we could make into a landing page.

[ffaf1]

What do you think about adding an unnumbered section "Welcome" at the very beginning. (I hope that unnumbered sections are possible) that we could make into a landing page.

That would be very good!

[gbaz]

"The guarantees about the stability of the CLI interface were written before the big v1- vs v2- split" -- this is not the cli interface for cabal-install, it is describing the Setup.hs cli interface of Cabal the library, which is not affected by the v1- v2- split. That information, and also the stability guarantees of the Cabal the library interface should be preserved.

I suggest the cabal the library interface stability information be moved to https://cabal.readthedocs.io/en/stable/cabal-package.html#custom-setup-scripts and the Setup.hs stability information be moved to the end of https://cabal.readthedocs.io/en/stable/setup-commands.html

[BinderDavid]

I have added a "Welcome" landing page which contains information on where to find the Haskell and Cabal community, and where to report bugs and feature requests in 1f6dbec

@gbaz As you suggested, I have added the stability info about the Setup.hs commandline interface to the end of the section which documents the Setup.hs interface in 8f0ff0d. But I don't know what part about the library information precisely is worth preserving. The section that is currently deleted contained the following information:

Functions and Types
-------------------

The Cabal library follows the `Package Versioning Policy`_.
This means that within a stable major release, for example 1.2.x, there
will be no incompatible API changes. But minor versions increments, for
example 1.2.3, indicate compatible API additions.

The Package Versioning Policy does not require any API guarantees
between major releases, for example between 1.2.x and 1.4.x. In practice
of course not everything changes between major releases. Some parts of
the API are more prone to change than others. The rest of this section
gives some informal advice on what level of API stability you can expect
between major releases.

Very Stable API
~~~~~~~~~~~~~~~

-  ``defaultMain``

-  ``defaultMainWithHooks defaultUserHooks``

But regular ``defaultMainWithHooks`` isn't stable since ``UserHooks``
changes.

Semi-stable API
~~~~~~~~~~~~~~~

-  ``UserHooks`` The hooks API will change in the future

-  ``Distribution.*`` is mostly declarative information about packages
   and is somewhat stable.

Unstable API
~~~~~~~~~~~~

Everything under ``Distribution.Simple.*`` has no stability guarantee.

The fact that UserHooks can change is already contained in the haddock comments in the API documentation: https://hackage.haskell.org/package/Cabal-3.10.2.0/docs/Distribution-Simple.html#t:UserHooks And if everything under Distribution.Simple does indeed not have any stability guarantee, doesn't that belong in the API documentation of the cabal library? The reference to defaultMain is also a bit ambiguous here: Does it only refer to Distribution.Simple or also to Distribution.Make? And I don't know what it means that Distribution.* is "somewhat stable".

[malteneuss]

Does the rewrite fit into an explanation section (what part of Cabal has what stability guarantess and maybe why) of #9379

[BinderDavid]

Does the rewrite fit into an explanation section (what part of Cabal has what stability guarantess and maybe why) of #9379

I don't think there needs to be a central "stability" section. The package description format is versioned and mostly backwards + forwards compatible. All changes to package descriptions are already mentioned there in the version history. The library is under PVP and has its own API description, which can document which parts of its surface are fragile. And none of the big changes were documented anywhere in the "stability" section, but could be found in the changelogs. In my opinion the stability section currently looks like it might contain actually useful information about changes to cabal for users, but it doesn't document any of the really relevant changes.

[malteneuss]

What do you think about moving this section into a separate guide page like https://github.com/haskell/cabal/pull/9379/files#diff-495e1081527403be1d72a3ae8c14fa5cfa19754bffd27c7b6f4455fa589d1836? It would help with SEO to have the page slug also mention "how-to-get-help-report-issues".

[malteneuss]

If the lower part becomes a dedicated page, would this section make more sense on the getting-started page?

[BinderDavid]

I have just rebased on top of #9379

@malteneuss I think that a small welcome section would make sense, with the intention that we can place some of the very general information there which doesn't really fit in any of the categories. How to contact the devs and report bugs doesn't seem to me to be worth of its own guide section for example. WDYT?