From: Bob Beck Date: Tue, 25 Nov 2025 19:24:55 +0000 (-0700) Subject: Start the 4.0 migration guide X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=d292c363b92bd92d0a8c8f2fe99b283307dbb6fb;p=thirdparty%2Fopenssl.git Start the 4.0 migration guide This includes adding a little internal procedure for when functions are removed, and a special ossl-ex-api page to document what API has been removed. Reviewed-by: Matt Caswell Reviewed-by: Norbert Pocs (Merged from https://github.com/openssl/openssl/pull/29220) --- diff --git a/doc/build.info b/doc/build.info index d7e169e5802..ed6b7d1afed 100644 --- a/doc/build.info +++ b/doc/build.info @@ -5085,6 +5085,10 @@ DEPEND[html/man7/ossl-guide-tls-server-block.html]=man7/ossl-guide-tls-server-bl GENERATE[html/man7/ossl-guide-tls-server-block.html]=man7/ossl-guide-tls-server-block.pod DEPEND[man/man7/ossl-guide-tls-server-block.7]=man7/ossl-guide-tls-server-block.pod GENERATE[man/man7/ossl-guide-tls-server-block.7]=man7/ossl-guide-tls-server-block.pod +DEPEND[html/man7/ossl-removed-api.html]=man7/ossl-removed-api.pod +GENERATE[html/man7/ossl-removed-api.html]=man7/ossl-removed-api.pod +DEPEND[man/man7/ossl-removed-api.7]=man7/ossl-removed-api.pod +GENERATE[man/man7/ossl-removed-api.7]=man7/ossl-removed-api.pod DEPEND[html/man7/ossl_store-file.html]=man7/ossl_store-file.pod GENERATE[html/man7/ossl_store-file.html]=man7/ossl_store-file.pod DEPEND[man/man7/ossl_store-file.7]=man7/ossl_store-file.pod @@ -5319,6 +5323,7 @@ html/man7/ossl-guide-tls-client-block.html \ html/man7/ossl-guide-tls-client-non-block.html \ html/man7/ossl-guide-tls-introduction.html \ html/man7/ossl-guide-tls-server-block.html \ +html/man7/ossl-removed-api.html \ html/man7/ossl_store-file.html \ html/man7/ossl_store.html \ html/man7/passphrase-encoding.html \ @@ -5478,6 +5483,7 @@ man/man7/ossl-guide-tls-client-block.7 \ man/man7/ossl-guide-tls-client-non-block.7 \ man/man7/ossl-guide-tls-introduction.7 \ man/man7/ossl-guide-tls-server-block.7 \ +man/man7/ossl-removed-api.7 \ man/man7/ossl_store-file.7 \ man/man7/ossl_store.7 \ man/man7/passphrase-encoding.7 \ diff --git a/doc/internal/man7/removal.pod b/doc/internal/man7/removal.pod new file mode 100644 index 00000000000..93c109e5e08 --- /dev/null +++ b/doc/internal/man7/removal.pod @@ -0,0 +1,79 @@ +=pod + +=head1 NAME + +removal - How to do Public API removal + +=head1 DESCRIPTION + +Removal of a public function should only be done after it has been +previously deprecated as documented in L. + +Once you are ready to remove a deprecated function, you need to +ensure one or more of the following things is true: + +=over 4 + +=item There is a usually straightforward one-to-one replacement of the +deleted function with a new function. + +=item The previous release documents how to replace the function. If +you feel this documentation is inadequate or incomplete, consider +updating it if a maintenance release will happen. + +=item Details on how to replace the function are provided in +L. If the replacement is complex and was +not adequately documented in the past release, it is a good idea +to write a reasonable section here. + +=back + +Once that is done, you should prepare your PR that removes the +function, internal uses, and documentation. + +Your PR removing functions should include adding the function to the +list in L with an appropriate entry. Keep it short and +simple. Each entry in the list for a version may include a quick link +to the usual replacement such as: + +=over 4 + +=item SIMPLE-removed-function (Deprecated in 3.0.0) see SIMPLE-replacement-function(3) + +=back + +If is more complex, mention that the documentation for a previous version should be +consulted, such as: + +=over 4 + +=item REMOVED-morecomplex (Deprecated in 3.0.0) Consult the documentation in OpenSSL 3.6 + +=back + +Alternatively, if a section covering this is in the migration guide: + +=over 4 + +=item ENGINE-allthethings (Deprecated in 3.0.0) Consult L. + +=back + +The list should NOT include a long migration guide. That should have been present +in the previous version documentation, or added to ossl-guide-migration.pod + +=head1 SEE ALSO + +L +L + +=head1 COPYRIGHT + +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut diff --git a/doc/man7/ossl-guide-migration.pod b/doc/man7/ossl-guide-migration.pod index b36916072e3..ad2d5308848 100644 --- a/doc/man7/ossl-guide-migration.pod +++ b/doc/man7/ossl-guide-migration.pod @@ -17,6 +17,26 @@ L. For an overview of some of the key concepts introduced in OpenSSL 3.0 see L. +=head1 OPENSSL 4.0 + +=head2 Main Changes from OpenSSL 3.6 + +=head3 Major Release + +OpenSSL 4.0 is a major release and consequently any application that +currently uses an older version of OpenSSL will at the very least need +to be recompiled in order to work with the new version. It is the +intention that many applications will work unchanged with OpenSSL +4.0 if those applications previously worked with OpenSSL 3.6 and did +not use deprecated API. However this is not guaranteed and some +changes may be required in some cases. Changes may be required to +applications using previously deprecated API. Changes may also be +required if applications need to take advantage of some of the new +features available in OpenSSL 4.0. + +Some functions have been removed that were deprecated in previous +versions of OpenSSL. See L. + =head1 OPENSSL 3.6 =head2 Main Changes from OpenSSL 3.5 diff --git a/doc/man7/ossl-removed-api.pod b/doc/man7/ossl-removed-api.pod new file mode 100644 index 00000000000..4e2e5660a38 --- /dev/null +++ b/doc/man7/ossl-removed-api.pod @@ -0,0 +1,53 @@ +=pod + +=head1 NAME + +ASN1_STRING_data, +ossl-removed-api - API that has been removed from OpenSSL + +=head1 SYNOPSIS + +This page lists API that has been removed from OpenSSL, and when it was removed. + +=head1 DESCRIPTION + +This page documents a list of API that has been removed from +OpenSSL. Functions are not removed until they have been deprecated for +some time (Normally at least one major OpenSSL release, if not +more). This means that during at least one previous major release of +OpenSSL, deprecation warnings would have been emitted at compile time +when using this function, and the documentation would have contained +information on how to move away from the deprecated API. + +Once a deprecated function is removed, The documentation for that +function will also be removed in order to keep the documentation +relevant to the current release. Normally, you should consult a +previous major release of OpenSSL where this function still existed, +and make changes to your code to no longer use the function as +documented in that release. + +This includes consulting the L documentation. + +=head1 OPENSSL 4.0 + +=over 4 + +=item ASN1_STRING_data (Deprecated in 1.1.1) - see L + +=back + +=head1 SEE ALSO + +L + +=head1 COPYRIGHT + +Copyright 2025 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the Apache License 2.0 (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L. + +=cut +