[Docs] Clarify typed pointers support timeline

[nikic]

Summary

As there have been a couple of questions about this recently, this gives a hard timeline on typed pointers support.

Given that we are about a month away from LLVM 16 branching, I think we should retain best-effort typed pointer support in LLVM 16 even if we get all tests migrated before that point.

Conversely, regardless of what the actual test migration state will be at that point, I believe we should un-support typed pointers by policy immediately after branching. Once release/16.x has been branched, typed pointers on main will no longer be supported (and can be actively broken). We only need to keep not-yet-migrated tests working, if there are any left at that point.

[arsenm]

I think this makes sense

llvm/docs/OpaquePointers.rst

 Version Support
 ===============
 
 **LLVM 14:** Supports all necessary APIs for migrating to opaque pointers and deprecates/removes incompatible APIs. However, using opaque pointers in the optimization pipeline is **not** fully supported. This release can be used to make out-of-tree code compatible with opaque pointers, but opaque pointers should **not** be enabled in production.
 
 **LLVM 15:** Opaque pointers are enabled by default. Typed pointers are still
 supported.
 
-**LLVM 16:** Only opaque pointers will be supported. Typed pointers will not be supported.
+**LLVM 16:** Opaque pointers are enabled by default. Typed pointers are
+supported on a best-effort basis only and not tested.
+
+**LLVM 17:** Only opaque pointers are supported. Typed pointers are not
+supported.
 
 Transition State
 ================
 
-As of December 2022 (LLVM 16):
-
-Typed pointers are currently still supported on a best-effort basis. Patches to
-fix typed pointer support are accepted, but must not include test coverage.
+As of December 2022:
 
 Tests are in the process of being converted to opaque pointers. All new tests
-must use opaque pointers. Typed pointer support will be removed as soon as test
-migration finishes.
+must use opaque pointers.
+
+Typed pointers are supported on a best-effort basis in LLVM 16, but are *not*
+supported in LLVM 17. Fixes for typed pointer support will be accepted on the
+``main`` branch only until the creation of the ``release/16.x`` branch
+(expected on Jan 24th 2023). After that point, typed pointer support on the
+``main`` branch will only be retained to the degree that is necessary to not
+break tests that haven't been migrated yet.
 
 The following typed pointer functionality has already been removed:
 
 * The ``CLANG_ENABLE_OPAQUE_POINTERS`` cmake flag is no longer supported.
 * C APIs that do not support opaque pointers (like ``LLVMBuildLoad``) are no
   longer supported.
 * Typed pointer bitcode is implicitly upgraded to use opaque pointers, unless
   ``-opaque-pointers=0`` is passed.
 
 The following typed pointer functionality is still to be removed:
 
 * The ``-no-opaque-pointers`` cc1 flag, ``-opaque-pointers=0`` opt flag and
   ``-plugin-opt=no-opaque-pointers`` lto flag.
 * Auto-detection of typed pointers in textual IR.
 * Support for typed pointers in LLVM libraries.