doc: add the migration guide to the new guide series

Reviewed-by: Hugo Landau <hlandau@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21807)

7 files changed, 18 insertions, 15 deletions

diff --git a/README.md b/README.md
index 5d5f1b8cc9..c620649381 100644
--- a/README.md
+++ b/README.md
@@ -114,7 +114,7 @@ document.
  * [Notes on Valgrind](NOTES-VALGRIND.md)
 
 Specific notes on upgrading to OpenSSL 3.0 from previous versions can be found
-in the [migration_guide(7ossl)] manual page.
+in the [ossl-guide-migration(7ossl)] manual page.
 
 Documentation
 =============
@@ -194,8 +194,8 @@ All rights reserved.
     <https://wiki.openssl.org>
     "OpenSSL Wiki"
 
-[migration_guide(7ossl)]:
-    <https://www.openssl.org/docs/manmaster/man7/migration_guide.html>
+[ossl-guide-migration(7ossl)]:
+    <https://www.openssl.org/docs/manmaster/man7/ossl-guide-migration.html>
     "OpenSSL Migration Guide"
 
 [RFC 8446]:
diff --git a/dev/release-aux/openssl-announce-pre-release.tmpl b/dev/release-aux/openssl-announce-pre-release.tmpl
index 470a42bdd3..cf30488e93 100644
--- a/dev/release-aux/openssl-announce-pre-release.tmpl
+++ b/dev/release-aux/openssl-announce-pre-release.tmpl
@@ -15,7 +15,7 @@
    Specific notes on upgrading to OpenSSL $series from previous versions are
    available in the OpenSSL Migration Guide, here:
 
-        https://www.openssl.org/docs/manmaster/man7/migration_guide.html
+        https://www.openssl.org/docs/manmaster/man7/ossl-guide-migration.html
 
    The $label release is available for download via HTTPS and FTP from the
    following master locations (you can find the various FTP mirrors under
diff --git a/dev/release-aux/openssl-announce-release.tmpl b/dev/release-aux/openssl-announce-release.tmpl
index fcd8087bf3..ce1dc7550a 100644
--- a/dev/release-aux/openssl-announce-release.tmpl
+++ b/dev/release-aux/openssl-announce-release.tmpl
@@ -14,7 +14,7 @@
    Specific notes on upgrading to OpenSSL $series from previous versions are
    available in the OpenSSL Migration Guide, here:
 
-        https://www.openssl.org/docs/man$series/man7/migration_guide.html
+        https://www.openssl.org/docs/man$series/man7/ossl-guide-migration.html
 
    OpenSSL $release is available for download via HTTPS and FTP from the
    following master locations (you can find the various FTP mirrors under
diff --git a/doc/build.info b/doc/build.info
index 68cfd6ff39..829fe55682 100644
--- a/doc/build.info
+++ b/doc/build.info
@@ -4721,10 +4721,6 @@ DEPEND[html/man7/life_cycle-rand.html]=man7/life_cycle-rand.pod
 GENERATE[html/man7/life_cycle-rand.html]=man7/life_cycle-rand.pod
 DEPEND[man/man7/life_cycle-rand.7]=man7/life_cycle-rand.pod
 GENERATE[man/man7/life_cycle-rand.7]=man7/life_cycle-rand.pod
-DEPEND[html/man7/migration_guide.html]=man7/migration_guide.pod
-GENERATE[html/man7/migration_guide.html]=man7/migration_guide.pod
-DEPEND[man/man7/migration_guide.7]=man7/migration_guide.pod
-GENERATE[man/man7/migration_guide.7]=man7/migration_guide.pod
 DEPEND[html/man7/openssl-core.h.html]=man7/openssl-core.h.pod
 GENERATE[html/man7/openssl-core.h.html]=man7/openssl-core.h.pod
 DEPEND[man/man7/openssl-core.h.7]=man7/openssl-core.h.pod
@@ -4775,6 +4771,10 @@ DEPEND[html/man7/ossl-guide-libssl-introduction.html]=man7/ossl-guide-libssl-int
 GENERATE[html/man7/ossl-guide-libssl-introduction.html]=man7/ossl-guide-libssl-introduction.pod
 DEPEND[man/man7/ossl-guide-libssl-introduction.7]=man7/ossl-guide-libssl-introduction.pod
 GENERATE[man/man7/ossl-guide-libssl-introduction.7]=man7/ossl-guide-libssl-introduction.pod
+DEPEND[html/man7/ossl-guide-migration.html]=man7/ossl-guide-migration.pod
+GENERATE[html/man7/ossl-guide-migration.html]=man7/ossl-guide-migration.pod
+DEPEND[man/man7/ossl-guide-migration.7]=man7/ossl-guide-migration.pod
+GENERATE[man/man7/ossl-guide-migration.7]=man7/ossl-guide-migration.pod
 DEPEND[html/man7/ossl-guide-quic-client-block.html]=man7/ossl-guide-quic-client-block.pod
 GENERATE[html/man7/ossl-guide-quic-client-block.html]=man7/ossl-guide-quic-client-block.pod
 DEPEND[man/man7/ossl-guide-quic-client-block.7]=man7/ossl-guide-quic-client-block.pod
@@ -4985,7 +4985,6 @@ html/man7/life_cycle-kdf.html \
 html/man7/life_cycle-mac.html \
 html/man7/life_cycle-pkey.html \
 html/man7/life_cycle-rand.html \
-html/man7/migration_guide.html \
 html/man7/openssl-core.h.html \
 html/man7/openssl-core_dispatch.h.html \
 html/man7/openssl-core_names.h.html \
@@ -4998,6 +4997,7 @@ html/man7/ossl-guide-introduction.html \
 html/man7/ossl-guide-libcrypto-introduction.html \
 html/man7/ossl-guide-libraries-introduction.html \
 html/man7/ossl-guide-libssl-introduction.html \
+html/man7/ossl-guide-migration.html \
 html/man7/ossl-guide-quic-client-block.html \
 html/man7/ossl-guide-quic-introduction.html \
 html/man7/ossl-guide-tls-client-block.html \
@@ -5124,7 +5124,6 @@ man/man7/life_cycle-kdf.7 \
 man/man7/life_cycle-mac.7 \
 man/man7/life_cycle-pkey.7 \
 man/man7/life_cycle-rand.7 \
-man/man7/migration_guide.7 \
 man/man7/openssl-core.h.7 \
 man/man7/openssl-core_dispatch.h.7 \
 man/man7/openssl-core_names.h.7 \
@@ -5137,6 +5136,7 @@ man/man7/ossl-guide-introduction.7 \
 man/man7/ossl-guide-libcrypto-introduction.7 \
 man/man7/ossl-guide-libraries-introduction.7 \
 man/man7/ossl-guide-libssl-introduction.7 \
+man/man7/ossl-guide-migration.7 \
 man/man7/ossl-guide-quic-client-block.7 \
 man/man7/ossl-guide-quic-introduction.7 \
 man/man7/ossl-guide-tls-client-block.7 \
diff --git a/doc/man7/fips_module.pod b/doc/man7/fips_module.pod
index 8c21854862..9756a89f06 100644
--- a/doc/man7/fips_module.pod
+++ b/doc/man7/fips_module.pod
@@ -42,7 +42,7 @@ EC_KEY_METHOD_new(), etc.)
 =back
 
 All of the above APIs are deprecated in OpenSSL 3.0 - so a simple rule is to
-avoid using all deprecated functions. See L<migration_guide(7)> for a list of
+avoid using all deprecated functions. See L<ossl-guide-migration(7)> for a list of
 deprecated functions.
 
 =head2 Making all applications use the FIPS module by default
@@ -393,7 +393,7 @@ explicitly loaded, the default provider will not automatically load. This means
 code using the default context by accident will fail because no algorithms will
 be available.
 
-See L<migration_guide(7)/Library Context> for additional information about the
+See L<ossl-guide-migration(7)/Library Context> for additional information about the
 Library Context.
 
 =head2 Using Encoders and Decoders with the FIPS module
@@ -500,7 +500,7 @@ want to operate in a FIPS approved manner.  The algorithms are:
 
 =head1 SEE ALSO
 
-L<migration_guide(7)>, L<crypto(7)>, L<fips_config(5)>,
+L<ossl-guide-migration(7)>, L<crypto(7)>, L<fips_config(5)>,
 L<https://www.openssl.org/source/>
 
 =head1 HISTORY
diff --git a/doc/man7/ossl-guide-introduction.pod b/doc/man7/ossl-guide-introduction.pod
index 655c4c9111..4e918ad85e 100644
--- a/doc/man7/ossl-guide-introduction.pod
+++ b/doc/man7/ossl-guide-introduction.pod
@@ -81,6 +81,8 @@ The pages in the guide are as follows:
 
 =item L<ossl-guide-quic-client-block(7)>: Writing a simple blocking QUIC client
 
+=item L<ossl-guide-migration(7)>: Migrating from older OpenSSL versions
+
 =back
 
 =head1 COPYRIGHT
diff --git a/doc/man7/migration_guide.pod b/doc/man7/ossl-guide-migration.pod
index 5294f57225..1042744d66 100644
--- a/doc/man7/migration_guide.pod
+++ b/doc/man7/ossl-guide-migration.pod
@@ -2,7 +2,8 @@
 
 =head1 NAME
 
-migration_guide - OpenSSL migration guide
+ossl-guide-migration, migration_guide
+- OpenSSL Guide: Migrating from older OpenSSL versions
 
 =head1 SYNOPSIS