Commit 700019fb66 for openssl.org

commit 700019fb6689cafb3c9ec035af5adb4ba667e80d
Author: Eugene Syromiatnikov <esyr@openssl.org>
Date:   Mon Aug 3 16:05:25 2026 +0200

    doc/internal/man7/deprecation.pod: document OSSL_DEPRECATEDIN_._._FOR macros

    Signed-off-by: Eugene Syromiatnikov <esyr@openssl.org>

    Reviewed-by: Nikola Pajkovsky <nikolap@openssl.org>
    Reviewed-by: Frederik Wedel-Heinen <fwh.openssl@gmail.com>
    MergeDate: Tue Aug 11 07:00:52 2026
    (Merged from https://github.com/openssl/openssl/pull/32155)

diff --git a/doc/internal/man7/deprecation.pod b/doc/internal/man7/deprecation.pod
index f27e664b49..69f4cb9bee 100644
--- a/doc/internal/man7/deprecation.pod
+++ b/doc/internal/man7/deprecation.pod
@@ -2,19 +2,19 @@

 =head1 NAME

-OPENSSL_NO_DEPRECATED_4_1, OSSL_DEPRECATEDIN_4_1,
-OPENSSL_NO_DEPRECATED_4_0, OSSL_DEPRECATEDIN_4_0,
-OPENSSL_NO_DEPRECATED_3_6, OSSL_DEPRECATEDIN_3_6,
-OPENSSL_NO_DEPRECATED_3_5, OSSL_DEPRECATEDIN_3_5,
-OPENSSL_NO_DEPRECATED_3_4, OSSL_DEPRECATEDIN_3_4,
-OPENSSL_NO_DEPRECATED_3_1, OSSL_DEPRECATEDIN_3_1,
-OPENSSL_NO_DEPRECATED_3_0, OSSL_DEPRECATEDIN_3_0,
-OPENSSL_NO_DEPRECATED_1_1_1, OSSL_DEPRECATEDIN_1_1_1,
-OPENSSL_NO_DEPRECATED_1_1_0, OSSL_DEPRECATEDIN_1_1_0,
-OPENSSL_NO_DEPRECATED_1_0_2, OSSL_DEPRECATEDIN_1_0_2,
-OPENSSL_NO_DEPRECATED_1_0_1, OSSL_DEPRECATEDIN_1_0_1,
-OPENSSL_NO_DEPRECATED_1_0_0, OSSL_DEPRECATEDIN_1_0_0,
-OPENSSL_NO_DEPRECATED_0_9_8, OSSL_DEPRECATEDIN_0_9_8,
+OPENSSL_NO_DEPRECATED_4_1, OSSL_DEPRECATEDIN_4_1, OSSL_DEPRECATEDIN_4_1_FOR,
+OPENSSL_NO_DEPRECATED_4_0, OSSL_DEPRECATEDIN_4_0, OSSL_DEPRECATEDIN_4_0_FOR,
+OPENSSL_NO_DEPRECATED_3_6, OSSL_DEPRECATEDIN_3_6, OSSL_DEPRECATEDIN_3_6_FOR,
+OPENSSL_NO_DEPRECATED_3_5, OSSL_DEPRECATEDIN_3_5, OSSL_DEPRECATEDIN_3_5_FOR,
+OPENSSL_NO_DEPRECATED_3_4, OSSL_DEPRECATEDIN_3_4, OSSL_DEPRECATEDIN_3_4_FOR,
+OPENSSL_NO_DEPRECATED_3_1, OSSL_DEPRECATEDIN_3_1, OSSL_DEPRECATEDIN_3_1_FOR,
+OPENSSL_NO_DEPRECATED_3_0, OSSL_DEPRECATEDIN_3_0, OSSL_DEPRECATEDIN_3_0_FOR,
+OPENSSL_NO_DEPRECATED_1_1_1, OSSL_DEPRECATEDIN_1_1_1, OSSL_DEPRECATEDIN_1_1_1_FOR,
+OPENSSL_NO_DEPRECATED_1_1_0, OSSL_DEPRECATEDIN_1_1_0, OSSL_DEPRECATEDIN_1_1_0_FOR,
+OPENSSL_NO_DEPRECATED_1_0_2, OSSL_DEPRECATEDIN_1_0_2, OSSL_DEPRECATEDIN_1_0_2_FOR,
+OPENSSL_NO_DEPRECATED_1_0_1, OSSL_DEPRECATEDIN_1_0_1, OSSL_DEPRECATEDIN_1_0_1_FOR,
+OPENSSL_NO_DEPRECATED_1_0_0, OSSL_DEPRECATEDIN_1_0_0, OSSL_DEPRECATEDIN_1_0_0_FOR,
+OPENSSL_NO_DEPRECATED_0_9_8, OSSL_DEPRECATEDIN_0_9_8, OSSL_DEPRECATEDIN_0_9_8_FOR,
 deprecation - How to do deprecation

 =head1 DESCRIPTION
@@ -34,7 +34,14 @@ configuration option C<--api>, or if the user chooses to do so, with
 L<OPENSSL_API_COMPAT(7)>).

 Deprecation is done using attribute macros named
-B<OSSL_DEPRECATEDIN_I<version>>, used with any declaration it applies to.
+B<OSSL_DEPRECATEDIN_I<version>> and B<OSSL_DEPRECATEDIN_I<version>_FOR>,
+used with any declaration it applies to.
+B<OSSL_DEPRECATEDIN_I<version>_FOR>(I<reason>) is the preferable macro variant
+to use, as it provides ability to communicate to the user (via the I<reason>
+argument) the reason a particular symbol has been deprecated, and point out
+the migration path;
+I<reason> should be provided without leading spaces, without capitalisation
+of the first word, and without a terminating period.

 Simulating removal is done with C<#ifndef> preprocessor guards using macros
 named B<OPENSSL_NO_DEPRECATED_I<version>>.