re.pm - add notes that the debug output is NOT a "supported API".

The debug output leaks a large amount of information about the
implementation details of the regex engine and as such is highly likely
to change based on almost any change to the regex engine. Also from time
to time we make changes to the output to improve legibility, etc. While
the output of C<use re 'debug'> is intended for user consumption as well
as for debugging the regex engine itself I believe that we should not
provide any backcompat guarantees about its specific contents or format.
Similarly the list of options we provide for C<use re 'Debug'> may be
affected by changes in the internals of the engine, rending old
categories irrelevant, or requiring new categories to be added.

This patch adds language to the C<re.pm> docs that stipulate that the
debug options we provide under C<use re 'Debug'> and the output we
provide from C<use re 'debug'> and C<use re 'Debug'> are subject to
change without notice at any major or minor release.

While I do not anticipate changes to the output in a minor release I
believe it is wise to specify that we do not commit ourselves to
consistency in this regard in any way. For instance were the situation
to arise that we had a security issue or serious performance issues or
some other strong justification to make a change in a minor release then
this could very well change the output we provide or the options we
support.

0 files changed, 0 insertions, 0 deletions