From aa873d3a224081a18cb13cec972a386b89a9b86d Mon Sep 17 00:00:00 2001 From: Madhura Bhave Date: Wed, 9 Jun 2021 21:36:28 -0700 Subject: [PATCH] Reorder documentation overview section The documentation overview sections is supposed to provide a map for the rest of the reference document. The getting help and upgrading sections were moved to align with that. --- .../src/docs/asciidoc/actuator/from-1x.adoc | 5 ++++ .../src/docs/asciidoc/documentation.adoc | 11 +++----- .../docs/asciidoc/documentation/about.adoc | 9 ------- .../asciidoc/documentation/getting-help.adoc | 16 ------------ .../asciidoc/documentation/upgrading.adoc | 12 +++++---- .../docs/asciidoc/documentation/using.adoc | 2 +- .../src/docs/asciidoc/getting-help.adoc | 18 +++++++++++++ .../asciidoc/getting-started/installing.adoc | 26 ------------------- .../src/docs/asciidoc/index.adoc | 5 +++- .../src/docs/asciidoc/index.singleadoc | 5 ++++ .../src/docs/asciidoc/upgrading.adoc | 15 +++++++++++ .../src/docs/asciidoc/upgrading/cli.adoc | 5 ++++ .../src/docs/asciidoc/upgrading/from-1x.adoc | 5 ++++ .../docs/asciidoc/upgrading/to-feature.adoc | 19 ++++++++++++++ .../src/docs/asciidoc/using.adoc | 2 +- 15 files changed, 89 insertions(+), 66 deletions(-) create mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/from-1x.adoc delete mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/about.adoc delete mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/getting-help.adoc create mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-help.adoc create mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading.adoc create mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/cli.adoc create mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/from-1x.adoc create mode 100644 spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/to-feature.adoc diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/from-1x.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/from-1x.adoc new file mode 100644 index 0000000000..10b440cac8 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/from-1x.adoc @@ -0,0 +1,5 @@ +[[upgrading.from-1x]] +== Upgrading from 1.x + +If you are upgrading from the `1.x` release of Spring Boot, check the {github-wiki}/Spring-Boot-2.0-Migration-Guide["`migration guide`" on the project wiki] that provides detailed upgrade instructions. +Check also the {github-wiki}["`release notes`"] for a list of "`new and noteworthy`" features for each release. \ No newline at end of file diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation.adoc index bce98f62d0..759efc3b03 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation.adoc @@ -3,7 +3,7 @@ include::attributes.adoc[] [[documentation]] -= Spring Boot Documentation += Documentation Overview include::attributes.adoc[] @@ -11,20 +11,17 @@ include::attributes.adoc[] This section provides a brief overview of Spring Boot reference documentation. It serves as a map for the rest of the document. +The latest copy of this document is available at {spring-boot-current-docs}. -include::documentation/about.adoc[] - -include::documentation/getting-help.adoc[] +include::documentation/first-steps.adoc[] include::documentation/upgrading.adoc[] -include::documentation/first-steps.adoc[] - include::documentation/using.adoc[] include::documentation/features.adoc[] include::documentation/actuator.adoc[] -include::documentation/advanced.adoc[] +include::documentation/advanced.adoc[] \ No newline at end of file diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/about.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/about.adoc deleted file mode 100644 index 4538620ff1..0000000000 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/about.adoc +++ /dev/null @@ -1,9 +0,0 @@ -[[documentation.about]] -== About the Documentation -The Spring Boot reference guide is available as: - -* {spring-boot-docs}/html/[Multi-page HTML] -* {spring-boot-docs}/htmlsingle/[Single page HTML] -* {spring-boot-docs}/pdf/spring-boot-reference.pdf[PDF] - -The latest copy is available at {spring-boot-current-docs}. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/getting-help.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/getting-help.adoc deleted file mode 100644 index 5ba7182b64..0000000000 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/getting-help.adoc +++ /dev/null @@ -1,16 +0,0 @@ -[[documentation.getting-help]] -== Getting Help -If you have trouble with Spring Boot, we would like to help. - -* Try the <>. - They provide solutions to the most common questions. -* Learn the Spring basics. - Spring Boot builds on many other Spring projects. - Check the https://spring.io[spring.io] web-site for a wealth of reference documentation. - If you are starting out with Spring, try one of the https://spring.io/guides[guides]. -* Ask a question. - We monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-boot[`spring-boot`]. -* Report bugs with Spring Boot at https://github.com/spring-projects/spring-boot/issues. - -NOTE: All of Spring Boot is open source, including the documentation. -If you find problems with the docs or if you want to improve them, please {spring-boot-code}[get involved]. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/upgrading.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/upgrading.adoc index 471205b6ce..314239c9ec 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/upgrading.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/upgrading.adoc @@ -1,9 +1,11 @@ [[documentation.upgrading]] == Upgrading From an Earlier Version -Instructions for how to upgrade from earlier versions of Spring Boot are provided on the project {github-wiki}[wiki]. -Follow the links in the {github-wiki}#release-notes[release notes] section to find the version that you want to upgrade to. - -Upgrading instructions are always the first item in the release notes. -If you are more than one release behind, please make sure that you also review the release notes of the versions that you jumped. You should always ensure that you are running a {github-wiki}/Supported-Versions[supported version] of Spring Boot. + +Depending on the version that you are upgrading to, you can find some additional tips here: + +* *From 1.x:* <> +* *To a new feature release:* <> +* *Spring Boot CLI:* <> + diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/using.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/using.adoc index c4c9fe1854..122466f852 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/using.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/documentation/using.adoc @@ -1,5 +1,5 @@ [[documentation.using]] -== Working with Spring Boot +== Developing with Spring Boot Ready to actually start using Spring Boot? <>: * *Build systems:* <> | <> | <> | <> diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-help.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-help.adoc new file mode 100644 index 0000000000..93c8cbdc82 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-help.adoc @@ -0,0 +1,18 @@ +[[getting-help]] += Getting Help +include::attributes.adoc[] + +If you have trouble with Spring Boot, we would like to help. + +* Try the <>. +They provide solutions to the most common questions. +* Learn the Spring basics. +Spring Boot builds on many other Spring projects. +Check the https://spring.io[spring.io] web-site for a wealth of reference documentation. +If you are starting out with Spring, try one of the https://spring.io/guides[guides]. +* Ask a question. +We monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-boot[`spring-boot`]. +* Report bugs with Spring Boot at https://github.com/spring-projects/spring-boot/issues. + +NOTE: All of Spring Boot is open source, including the documentation. +If you find problems with the docs or if you want to improve them, please {spring-boot-code}[get involved]. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started/installing.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started/installing.adoc index 43b1a6fb81..e1ba182dcc 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started/installing.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/getting-started/installing.adoc @@ -233,29 +233,3 @@ You should see the following output: Hello World! ---- - - -[[getting-started.installing.upgrading]] -=== Upgrading from an Earlier Version of Spring Boot -If you are upgrading from the `1.x` release of Spring Boot, check the {github-wiki}/Spring-Boot-2.0-Migration-Guide["`migration guide`" on the project wiki] that provides detailed upgrade instructions. -Check also the {github-wiki}["`release notes`"] for a list of "`new and noteworthy`" features for each release. - -When upgrading to a new feature release, some properties may have been renamed or removed. -Spring Boot provides a way to analyze your application's environment and print diagnostics at startup, but also temporarily migrate properties at runtime for you. -To enable that feature, add the following dependency to your project: - -[source,xml,indent=0,subs="verbatim"] ----- - - org.springframework.boot - spring-boot-properties-migrator - runtime - ----- - -WARNING: Properties that are added late to the environment, such as when using `@PropertySource`, will not be taken into account. - -NOTE: Once you're done with the migration, please make sure to remove this module from your project's dependencies. - -To upgrade an existing CLI installation, use the appropriate package manager command (for example, `brew upgrade`). -If you manually installed the CLI, follow the <>, remembering to update your `PATH` environment variable to remove any older references. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.adoc index 003a392be4..19feeae45c 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.adoc @@ -4,14 +4,17 @@ include::authors.adoc[] v{spring-boot-version} include::attributes.adoc[] +This document is also available as {spring-boot-docs}/html/[Multi-page HTML], {spring-boot-docs}/htmlsingle/[Single page HTML] and {spring-boot-docs}/pdf/spring-boot-reference.pdf[PDF]. The reference documentation consists of the following sections: [horizontal] <> :: Legal information. -<> :: About the Documentation, Getting Help, First Steps, and more. +<> :: Resources for getting help. +<> :: About the Documentation, First Steps, and more. <> :: Introducing Spring Boot, System Requirements, Servlet Containers, Installing Spring Boot, Developing Your First Spring Boot Application +<> :: Upgrading from 1.x, Upgrading to a new feature release, Upgrading the Spring Boot CLI <> :: Build Systems, Structuring Your Code, Configuration, Spring Beans and Dependency Injection, DevTools, and more. <> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more. <> :: Monitoring, Metrics, Auditing, and more. diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.singleadoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.singleadoc index ef77e019e9..25c6c144c6 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.singleadoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/index.singleadoc @@ -4,14 +4,19 @@ include::authors.adoc[] v{spring-boot-version} include::attributes.adoc[] +This document is also available as {spring-boot-docs}/html/[Multi-page HTML], {spring-boot-docs}/htmlsingle/[Single page HTML] and {spring-boot-docs}/pdf/spring-boot-reference.pdf[PDF]. include::legal.adoc[leveloffset=+1] +include::getting-help.adoc[leveloffset=+1] + include::documentation.adoc[leveloffset=+1] include::getting-started.adoc[leveloffset=+1] +include::upgrading.adoc[leveloffset=+1] + include::using.adoc[leveloffset=+1] include::features.adoc[leveloffset=+1] diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading.adoc new file mode 100644 index 0000000000..a7d72ccb79 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading.adoc @@ -0,0 +1,15 @@ +[[upgrading]] += Upgrading Spring Boot +include::attributes.adoc[] + +Instructions for how to upgrade from earlier versions of Spring Boot are provided on the project {github-wiki}[wiki]. +Follow the links in the {github-wiki}#release-notes[release notes] section to find the version that you want to upgrade to. + +Upgrading instructions are always the first item in the release notes. +If you are more than one release behind, please make sure that you also review the release notes of the versions that you jumped. + +include::upgrading/from-1x.adoc[] + +include::upgrading/to-feature.adoc[] + +include::upgrading/cli.adoc[] \ No newline at end of file diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/cli.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/cli.adoc new file mode 100644 index 0000000000..692c238105 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/cli.adoc @@ -0,0 +1,5 @@ +[[upgrading.cli]] +== Upgrading the Spring Boot CLI + +To upgrade an existing CLI installation, use the appropriate package manager command (for example, `brew upgrade`). +If you manually installed the CLI, follow the <>, remembering to update your `PATH` environment variable to remove any older references. \ No newline at end of file diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/from-1x.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/from-1x.adoc new file mode 100644 index 0000000000..10b440cac8 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/from-1x.adoc @@ -0,0 +1,5 @@ +[[upgrading.from-1x]] +== Upgrading from 1.x + +If you are upgrading from the `1.x` release of Spring Boot, check the {github-wiki}/Spring-Boot-2.0-Migration-Guide["`migration guide`" on the project wiki] that provides detailed upgrade instructions. +Check also the {github-wiki}["`release notes`"] for a list of "`new and noteworthy`" features for each release. \ No newline at end of file diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/to-feature.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/to-feature.adoc new file mode 100644 index 0000000000..1432559e63 --- /dev/null +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/upgrading/to-feature.adoc @@ -0,0 +1,19 @@ +[[upgrading.to-feature]] +== Upgrading to a new feature release + +When upgrading to a new feature release, some properties may have been renamed or removed. +Spring Boot provides a way to analyze your application's environment and print diagnostics at startup, but also temporarily migrate properties at runtime for you. +To enable that feature, add the following dependency to your project: + +[source,xml,indent=0,subs="verbatim"] +---- + + org.springframework.boot + spring-boot-properties-migrator + runtime + +---- + +WARNING: Properties that are added late to the environment, such as when using `@PropertySource`, will not be taken into account. + +NOTE: Once you're done with the migration, please make sure to remove this module from your project's dependencies. \ No newline at end of file diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using.adoc index 7f45c5faac..832abd9e86 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/using.adoc @@ -1,5 +1,5 @@ [[using]] -= Using Spring Boot += Developing with Spring Boot include::attributes.adoc[]