Is referring to GHC-proposals in GHC user manual bad practice or not?

[Oleg Grenrus]

I have a following question:
My lexer rules related proposal was recently accepted. The biggest part
of getting it in is writing documentation for it. While looking at
Divergence from Haskell 98 and Haskell 2010 section of the user manual,
in particular Lexical syntax, it already has See "GHC Proposal #229 for
the precise rules.".

Can I just the same? (I think there was an implicit acceptance of that
practice in e.g.
https://gitlab.haskell.org/ghc/ghc/-/merge_requests/1664#note_238759)

However, I think that referring to proposals text for "essential" bits
of information is a bad practice.
Because GHC proposals are sometimes amended, one have to look into
GitHub history to find out what were there for a particular time point
of a GHC release. Very laborous.

---

Currently there is 23 references to about a dozen of proposals. An
example are passages like

    In 9.0, the behavior of this extension changed, and now we require
that a negative literal must not be preceded by a closing token (see
    `GHC Proposal #229
<https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0229-whitespace-bang-patterns.rst>`__
    for the definition of a closing token).

or

     a future release will be
     turned off by default and then possibly removed. The reasons for
this and
     the deprecation schedule are described in `GHC proposal #30
    
<https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0030-remove-star-kind.rst>`__.

And there are better examples, which are references for more information,
not essential one, like

     See the proposal `DuplicateRecordFields without ambiguous field access
    
<https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0366-no-ambiguous-field-access.rst>`_
     and the documentation on :extension:`DuplicateRecordFields` for
further details.

(I'd put the internal user manual link first), or

    But these automatic eta-expansions may silently change the semantics
of the user's program,
    and deep skolemisation was removed from the language by
    `GHC Proposal #287
<https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0287-simplify-subsumption.rst>`__.
    This proposal has many more examples.

---

So to boil down my question, can I write

    Lexical syntax of identifiers and decimal numbers differs slightly
from the Haskell report.
    See GHC Proposal #403 for the precise rules and differences.

- Oleg