mirror of
https://github.com/openssl/openssl.git
synced 2026-01-18 17:11:31 +01:00
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 <matt@openssl.org> Reviewed-by: Norbert Pocs <norbertp@openssl.org> (Merged from https://github.com/openssl/openssl/pull/29220)
This commit is contained in:
Bob Beck
@@ -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 \
|
||||
|
||||
79
doc/internal/man7/removal.pod
Normal file
79
doc/internal/man7/removal.pod
Normal file
@@ -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<deprecation(7)>.
|
||||
|
||||
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<ossl-guide-migration(7)>. 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<ossl-removed-api(7)> 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<ossl-guide-migration(7)>.
|
||||
|
||||
=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<deprecation(7)>
|
||||
L<ossl-guide-migration(7)>
|
||||
|
||||
=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<https://www.openssl.org/source/license.html>.
|
||||
|
||||
=cut
|
||||
@@ -17,6 +17,26 @@ L<https://github.com/openssl/openssl/blob/master/CHANGES.md>.
|
||||
For an overview of some of the key concepts introduced in OpenSSL 3.0 see
|
||||
L<crypto(7)>.
|
||||
|
||||
=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<ossl-removed-api(7)>.
|
||||
|
||||
=head1 OPENSSL 3.6
|
||||
|
||||
=head2 Main Changes from OpenSSL 3.5
|
||||
|
||||
53
doc/man7/ossl-removed-api.pod
Normal file
53
doc/man7/ossl-removed-api.pod
Normal file
@@ -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<ossl-guide-migration(7)> documentation.
|
||||
|
||||
=head1 OPENSSL 4.0
|
||||
|
||||
=over 4
|
||||
|
||||
=item ASN1_STRING_data (Deprecated in 1.1.1) - see L<ASN1_STRING_get0_data(3)>
|
||||
|
||||
=back
|
||||
|
||||
=head1 SEE ALSO
|
||||
|
||||
L<ossl-guide-migration(7)>
|
||||
|
||||
=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<https://www.openssl.org/source/license.html>.
|
||||
|
||||
=cut
|
||||
|
||||
Reference in New Issue
Block a user