[Bug libstdc++/104881] New: Document libstdc++ ABI evolution for experimental features

[redi at gcc dot gnu.org]

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=104881

            Bug ID: 104881
           Summary: Document libstdc++ ABI evolution for experimental
                    features
           Product: gcc
           Version: 12.0
            Status: UNCONFIRMED
          Keywords: documentation
          Severity: normal
          Priority: P3
         Component: libstdc++
          Assignee: unassigned at gcc dot gnu.org
          Reporter: redi at gcc dot gnu.org
  Target Milestone: ---

It might be helpful if the API evolution page at
https://gcc.gnu.org/onlinedocs/libstdc++/manual/api.html contained details of
breaking changes to experimental features.

For example, gcc-9.1 was the first release with non-experimental C++17 support,
and had ABI changes to std::variant compared with previous releases (which is
why you shouldn't mix experimental features from different releases).

r8-1649-g705037247447f4 made the copy constructor trivial in some cases, making
8.1.0 incompatible with 7.x

r9-6369-g669a6fdcb436ae rewrote large parts of std::variant, making 9.1.0
incompatible with 8.x (and r9-7106-g038bc9bfd6dfd9 and 
r9-6715-gda97b98ad34145 made further changes).

Similarly, gcc-8.1.0 had triviality changes for std::optional (r8-6100), and
maybe again for 9.1.0 (r9-4229).


There needs to be a caveat about the documentation of those changes being
incomplete, so users don't assume that if it's not mentioned there, it's safe
to use across versions. It's not supported, and the doc should not be taken as
a guarantee of what can be relied on.