config yaml guide updates #32869

rolfedh · 2023-04-24T19:58:39Z

Fixes #32890

quarkus-bot · 2023-04-24T19:58:57Z

Thanks for your pull request!

The title of your pull request does not follow our editorial rules. Could you have a look?

title should preferably start with an uppercase character (if it makes sense!)

This message is automatically generated by a bot.

github-actions · 2023-04-24T20:28:13Z

🙈 The PR is closed and the preview is expired.

gsmet

Thanks, I added a couple of comments but I'd like @radcortez to have a look too.

docs/src/main/asciidoc/config-your-quarkus-applications-using-a-yaml-file_howto.adoc

rolfedh · 2023-05-09T16:48:44Z

Thanks for your review and comments, @gsmet & @radcortez. I've made some updates based on your suggestions and left a few suggestions from @radcortez open so I can ask for clarification when we meet tomorrow.

docs/src/main/asciidoc/config-yaml.adoc

radcortez

I left a couple of additional comments. Once those are resolved, I think it should be good to go. Thanks!

radcortez · 2023-07-05T09:37:32Z

I think @gsmet may still have some concerns.

rolfedh · 2023-07-05T10:20:53Z

Hi @gsmet. I welcome your thoughts and comments. I'm getting ready to put it through our official QE process and want to make sure the content is settled before then.

rolfedh · 2023-07-05T20:17:47Z

@gsmet I'm not sure whether to wait for your input. I've gone ahead and requested QE review via https://issues.redhat.com/browse/QUARKUS-3243. Please let me know if you would like me postpone.

gsmet

Review updated to clarify my thoughts: I'm unhappy with the current result.

It is less precise, sometimes incorrect, and far more verbose than it used to be.

Developers don't have a lot of time when they read documentation. If we are making every small detail extremely verbose, they won't read our documentation.
Also we really need to avoid adding very vague sentences that are not actually useful.

I tried to point out some of the issues but really it's a general impression about this update.

docs/src/main/asciidoc/config-yaml.adoc

gsmet · 2023-07-06T13:29:09Z

docs/src/main/asciidoc/config-yaml.adoc


-Remove the `src/main/resources/application.properties` and create a `src/main/resources/application.yaml` file.
+In the YAML configuration file, you can define a nested element inside an existing element to set configuration properties for your {project-name} application.


I don't understand this sentence and what it brings to the plate?

I mean, this is the basics of YAML so it's not an extra feature or something that should be in a separate paragraph?

I removed the "nested" term. This section is very basic but might help non-experts by showing an example configuration file. WDYT?

gsmet · 2023-07-06T13:36:52Z

docs/src/main/asciidoc/config-yaml.adoc

-== Expressions
+// meta:include::modules/proc_setting-custom-configuration-profiles-with-yaml.adoc[leveloffset=+2]
+[id="proc_setting-custom-configuration-profiles-with-yaml_{context}"]
+== Setting custom configuration profiles with YAML


I don't understand the value of this paragraph compared to the previous one.

Good point. Removed this section.

gsmet · 2023-07-06T13:39:18Z

docs/src/main/asciidoc/config-yaml.adoc

+// DELETE meta:include::modules/con_external-application-yaml-file-for-configuring-properties-at-runtime.adoc[leveloffset=+1]
+// CREATE meta:include::modules/proc_configure-properties-at-run-time-external-yaml.adoc[leveloffset=+1]
+[id="proc_configure-properties-at-run-time-external-yaml_{context}"]
+== Configure properties at run time


Don't we write it runtime? At least that's how we used to write it everywhere? Did it change?

IBM Style states:

run time, runtime noun - Write as two words to refer to the time at which an application runs (for example, “At run time, you can…”). - Write as one word to refer to the environment in which an application runs (for example, “The Java runtime is controlled by…”).

However, if you feel strongly about it, we can use runtime. Most users are probably fine with it as a single word. Just let me know.

gsmet · 2023-07-06T13:40:30Z

docs/src/main/asciidoc/config-yaml.adoc

+
+. To compile your {project-name} application in development mode, enter the following command from the project directory:
+
+.Compile your {project-name} application
+[source,bash]
+----
+./mvnw quarkus:dev
+----
+


I'm not sure of the value of this here?

Generally, this type of information is useful for non-expert users such as students. Red Hat generally gets complaints from newer users that our documentation assumes too much expertise or prior knowledge.

gsmet · 2023-07-06T13:41:30Z

docs/src/main/asciidoc/config-yaml.adoc


-== Configuration key conflicts
+Structured formats such as YAML only support a subset of the possible configuration namespace.
+The following procedure shows how to resolve a conflict between two configuration properties, `quarkus.http.cors` and `quarkus.http.cors.methods`, where one property is the prefix of another.


I'm not sure about the rules and maybe this needs to be discussed at a higher level but we are adding a ton of procedures/prerequisites and this adds a lot of noise when you are trying to find some information.

Please feel free to strike any information that doesn't add value for our customers.
In future projects, rather than trying to merge the community and product content, I'll adopt an "additive" process. That is, I'll ask the SME to identify which product content they want to migrate to the community docs first.

Or, if you feel like that's too much trouble, I can toss out this PR and we start over with the proposed "additive" process instead.

docs/src/main/asciidoc/config-yaml.adoc

rolfedh · 2023-07-06T15:46:44Z

Thanks again for these additional comments. I'm making further updates and replying to some of your questions.

rolfedh

Thanks for your feedback, @gsmet. I've made updates and am open to more. Please have a look at my replies in the open conversations.

docs/src/main/asciidoc/config-yaml.adoc

rolfedh · 2023-07-06T20:03:46Z

docs/src/main/asciidoc/config-yaml.adoc

+// DELETE meta:include::modules/con_external-application-yaml-file-for-configuring-properties-at-runtime.adoc[leveloffset=+1]
+// CREATE meta:include::modules/proc_configure-properties-at-run-time-external-yaml.adoc[leveloffset=+1]
+[id="proc_configure-properties-at-run-time-external-yaml_{context}"]
+== Configure properties at run time


IBM Style states:

run time, runtime noun - Write as two words to refer to the time at which an application runs (for example, “At run time, you can…”). - Write as one word to refer to the environment in which an application runs (for example, “The Java runtime is controlled by…”).

However, if you feel strongly about it, we can use runtime. Most users are probably fine with it as a single word. Just let me know.

rolfedh · 2023-07-06T20:08:23Z

docs/src/main/asciidoc/config-yaml.adoc


-== Configuration key conflicts
+Structured formats such as YAML only support a subset of the possible configuration namespace.
+The following procedure shows how to resolve a conflict between two configuration properties, `quarkus.http.cors` and `quarkus.http.cors.methods`, where one property is the prefix of another.


Please feel free to strike any information that doesn't add value for our customers.
In future projects, rather than trying to merge the community and product content, I'll adopt an "additive" process. That is, I'll ask the SME to identify which product content they want to migrate to the community docs first.

rolfedh · 2023-07-06T20:10:13Z

docs/src/main/asciidoc/config-yaml.adoc

+
+. To compile your {project-name} application in development mode, enter the following command from the project directory:
+
+.Compile your {project-name} application
+[source,bash]
+----
+./mvnw quarkus:dev
+----
+


Generally, this type of information is useful for non-expert users such as students. Red Hat generally gets complaints from newer users that our documentation assumes too much expertise or prior knowledge.

rolfedh · 2023-07-06T20:19:17Z

docs/src/main/asciidoc/config-yaml.adoc

-== Expressions
+// meta:include::modules/proc_setting-custom-configuration-profiles-with-yaml.adoc[leveloffset=+2]
+[id="proc_setting-custom-configuration-profiles-with-yaml_{context}"]
+== Setting custom configuration profiles with YAML


Good point. Removed this section.

rolfedh · 2023-07-06T20:24:24Z

docs/src/main/asciidoc/config-yaml.adoc


-== Configuration key conflicts
+Structured formats such as YAML only support a subset of the possible configuration namespace.
+The following procedure shows how to resolve a conflict between two configuration properties, `quarkus.http.cors` and `quarkus.http.cors.methods`, where one property is the prefix of another.


Or, if you feel like that's too much trouble, I can toss out this PR and we start over with the proposed "additive" process instead.

rolfedh · 2023-07-13T14:30:44Z

Closing this PR to stop adding to sunken costs. Starting over with updated priorities and methods.

quarkus-bot bot added the area/documentation label Apr 24, 2023

rolfedh force-pushed the document-yaml-config branch 4 times, most recently from 08aabf2 to d5a8dca Compare April 27, 2023 21:04

gsmet requested changes May 2, 2023

View reviewed changes

gsmet added triage/backport? and removed triage/backport? labels May 2, 2023

gsmet requested a review from radcortez May 2, 2023 08:33

radcortez reviewed May 2, 2023

View reviewed changes

docs/src/main/asciidoc/config-your-quarkus-applications-using-a-yaml-file_howto.adoc Outdated Show resolved Hide resolved

radcortez reviewed May 2, 2023

View reviewed changes

docs/src/main/asciidoc/config-your-quarkus-applications-using-a-yaml-file_howto.adoc Outdated Show resolved Hide resolved

radcortez reviewed May 2, 2023

View reviewed changes

docs/src/main/asciidoc/config-your-quarkus-applications-using-a-yaml-file_howto.adoc Outdated Show resolved Hide resolved

radcortez reviewed May 2, 2023

View reviewed changes

docs/src/main/asciidoc/config-your-quarkus-applications-using-a-yaml-file_howto.adoc Outdated Show resolved Hide resolved

radcortez reviewed May 2, 2023

View reviewed changes

docs/src/main/asciidoc/config-your-quarkus-applications-using-a-yaml-file_howto.adoc Outdated Show resolved Hide resolved

rolfedh force-pushed the document-yaml-config branch 4 times, most recently from df3ce41 to fcf093c Compare May 9, 2023 16:39

rolfedh force-pushed the document-yaml-config branch 5 times, most recently from 293e4e8 to f97bb6c Compare May 13, 2023 19:33

rolfedh closed this May 13, 2023

rolfedh force-pushed the document-yaml-config branch from f97bb6c to ba59762 Compare May 13, 2023 20:39

rolfedh force-pushed the document-yaml-config branch 2 times, most recently from 769090e to 283493e Compare May 18, 2023 17:47

rolfedh force-pushed the document-yaml-config branch 2 times, most recently from 634beb8 to 9c70135 Compare May 30, 2023 20:42

rolfedh force-pushed the document-yaml-config branch 2 times, most recently from 626ac8d to 8847b17 Compare July 4, 2023 20:13

radcortez reviewed Jul 4, 2023

View reviewed changes

docs/src/main/asciidoc/config-yaml.adoc Outdated Show resolved Hide resolved

radcortez reviewed Jul 4, 2023

View reviewed changes

docs/src/main/asciidoc/config-yaml.adoc Outdated Show resolved Hide resolved

radcortez reviewed Jul 4, 2023

View reviewed changes

docs/src/main/asciidoc/config-yaml.adoc Outdated Show resolved Hide resolved

radcortez reviewed Jul 4, 2023

View reviewed changes

docs/src/main/asciidoc/config-yaml.adoc Outdated Show resolved Hide resolved

radcortez requested changes Jul 4, 2023

View reviewed changes

rolfedh force-pushed the document-yaml-config branch from 8847b17 to e47de51 Compare July 5, 2023 00:26

radcortez approved these changes Jul 5, 2023

View reviewed changes

rolfedh force-pushed the document-yaml-config branch from e47de51 to 994ff8c Compare July 5, 2023 10:21

rolfedh requested a review from gsmet July 5, 2023 14:13

Config yaml guide updates

4f8ad84

rolfedh force-pushed the document-yaml-config branch from 994ff8c to 4f8ad84 Compare July 5, 2023 20:16

gsmet requested changes Jul 6, 2023

View reviewed changes

maxandersen reviewed Jul 6, 2023

View reviewed changes

docs/src/main/asciidoc/config-yaml.adoc Outdated Show resolved Hide resolved

rolfedh commented Jul 6, 2023

View reviewed changes

Revisions based on most recent comments from Guillaume and Max

cdac0a3

rolfedh closed this Jul 13, 2023

quarkus-bot bot added the triage/invalid This doesn't seem right label Jul 13, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

config yaml guide updates #32869

config yaml guide updates #32869

rolfedh commented Apr 24, 2023 •

edited

Loading

quarkus-bot bot commented Apr 24, 2023

github-actions bot commented Apr 24, 2023 •

edited

Loading

gsmet left a comment

rolfedh commented May 9, 2023

radcortez left a comment

radcortez commented Jul 5, 2023

rolfedh commented Jul 5, 2023

rolfedh commented Jul 5, 2023

gsmet left a comment •

edited

Loading

gsmet Jul 6, 2023

rolfedh Jul 6, 2023

gsmet Jul 6, 2023

rolfedh Jul 6, 2023

gsmet Jul 6, 2023

rolfedh Jul 6, 2023

gsmet Jul 6, 2023

rolfedh Jul 6, 2023

gsmet Jul 6, 2023

rolfedh Jul 6, 2023

rolfedh Jul 6, 2023

rolfedh commented Jul 6, 2023

rolfedh left a comment

rolfedh Jul 6, 2023

rolfedh Jul 6, 2023

rolfedh Jul 6, 2023

rolfedh Jul 6, 2023

rolfedh Jul 6, 2023

rolfedh commented Jul 13, 2023 •

edited

Loading


		Remove the `src/main/resources/application.properties` and create a `src/main/resources/application.yaml` file.
		In the YAML configuration file, you can define a nested element inside an existing element to set configuration properties for your {project-name} application.

config yaml guide updates #32869

config yaml guide updates #32869

Conversation

rolfedh commented Apr 24, 2023 • edited Loading

quarkus-bot bot commented Apr 24, 2023

github-actions bot commented Apr 24, 2023 • edited Loading

gsmet left a comment

Choose a reason for hiding this comment

rolfedh commented May 9, 2023

radcortez left a comment

Choose a reason for hiding this comment

radcortez commented Jul 5, 2023

rolfedh commented Jul 5, 2023

rolfedh commented Jul 5, 2023

gsmet left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rolfedh commented Jul 6, 2023

rolfedh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rolfedh commented Jul 13, 2023 • edited Loading

rolfedh commented Apr 24, 2023 •

edited

Loading

github-actions bot commented Apr 24, 2023 •

edited

Loading

gsmet left a comment •

edited

Loading

rolfedh commented Jul 13, 2023 •

edited

Loading