[m-rev.] for post-commit review: update the intro of the library manual

[Julien Fischer]

On Mon, 11 Aug 2025 at 16:01, Zoltan Somogyi <zoltan.somogyi at runbox.com> wrote:

> diff --git a/doc/mercury_library_manual.texi b/doc/mercury_library_manual.texi
> index f2d3b250a..63d0eca7e 100644
> --- a/doc/mercury_library_manual.texi
> +++ b/doc/mercury_library_manual.texi

...

> +To help you protect yourself
> +from depending on modules that are likely to change,
> +each module has a comment ``stability: low/medium/high'' at the top,
> +which gives an indication of the likely stability
> +of the interface to that module.
> +For modules whose stability is ``high'',
> +new functionality may be added to the interface,
> +but we envisage very few if any changes to the interface
> +of the sort that might break existing code.
> +For modules whose stability is ``medium'',
> +we expect that changes are more likely.
> +For modules whose stability is ``low'', such changes are highly likely.
> +If you want to minimize the possibility of your programs
> +requiring modification to work with new releases of the Mercury system,
> +we recommend that if possible you use only those modules
> +whose stability is described as either ``medium to high'' or ``high''.

The changes to the introduction are fine.

I think we need to reconsider / update some of the stability indications.

* builtin's stability is low, which seems questionable.

* The following also seems questionable:

  set_bbbtree.m:11:% Stability: low.
  set_ctree234.m:11:% Stability: high.
  set.m:11:% Stability: high.
  set_ordlist.m:11:% Stability: medium.
  set_tree234.m:11:% Stability: high.
  set_unordlist.m:11:% Stability: medium.

  All of the above are supposed to implement the same ADT.
  (Indeed set_ordlist *is* set.)

* Most of the modules for the int types have low stability.
  (Which may have been true eight years ago when they were added, it's
  certainly no longer true.)

Also, I think we should restrict the stability indication to low /
medium / high.
I'm not sure what sort of distinctions "medium to high" or "medium-low"
are trying to convey, but whatever they may be, it's too subtle for me.

Julien.