[WFLY-15746] WildFly Application Development Guide #448
Conversation
|
This is just a draft for docs team to review and contribute. |
emmartins
force-pushed
the
WFLY-15746
branch
from
d63b636 to
3f68b6f
Compare
| * The guide should have 2 major sections, one for first time/beginners app developers, and one for advanced app developers. | ||
|
|
||
| * The major section for first time app developers should include the following new content: | ||
| ** How to develop a first basic application (helloworld quickstart) from scratch using Maven, a complete user story walkthrough, which should include: |
There was a problem hiding this comment.
Do we think this is one quickstart or a small subset of quickstarts? I don't think it would be a massive number but it feels like there may be a few getting started approaches.
There was a problem hiding this comment.
This is just the first app from scratch, in my mind just the simplest hello world
There was a problem hiding this comment.
This development guide should have some guiding principles that showcases efficient way to develop with WildFly.
While Jakarta EE development does not strictly adhere to https://12factor.net, there are principles that makes developing and operating WildFly much more simpler.
In particular, having the codebase being the source of deployments is a key aspect.
We should recommend & showcase how to provision and configure WildFly using the wildfly-maven-plugin in a reproducible & automated manner.
When we ask the user to copy a XML snippet in standalone.xml, we are not providing them a mechanism to keep this change in sync with WildFly releases and put the onus on them to automate this.
Compared to using a CLI scripts to apply this change to a provisioned WildFly server, this is automated, testable without any change to make outside of the codebase.
There was a problem hiding this comment.
IMHO we should include guidance for upstream only features, but consider those as alternatives to the supported features. If an upstream feature is a good enhancement than we should prioritise getting it supported.
There was a problem hiding this comment.
I'm not sure to follow you.
This guide must focus on the best way to develop with WildFly. If or when this will go in a supported product (I suppose you mean JBoss EAP) should not impact how WildFly is documented.
There was a problem hiding this comment.
The comment above is also a good opportunity to split this dev guides in different focused guides that can then be picked and choose when a feature reach a downstream product.
There was a problem hiding this comment.
I mean this is the upstream for an EAP 8 guide, it should prioritise now on the supported features.
| *** How to create the application Maven Project, and add Red Hat Maven repositories and BOMs dependencies | ||
| *** How to package, deploy and run the application (war/bootable jar, web console) | ||
| *** How to add logging to the application (basic usage) | ||
| *** How to test the application |
There was a problem hiding this comment.
Would it be worth in this section having something like "How to make the first modification" - i.e. the user has moved just beyond deploying an example we provide and made it their own with a small change?
There was a problem hiding this comment.
Please note that there is a quick start guide also, and that should provide just a deploy and run, in this one there is the coding of the hello world, and any further modification is then related with a specific technology (line 53)
|
|
||
| * The major section for first time app developers should include the following new content: | ||
| ** How to develop a first basic application (helloworld quickstart) from scratch using Maven, a complete user story walkthrough, which should include: | ||
| *** How to create the application Maven Project, and add Red Hat Maven repositories and BOMs dependencies |
There was a problem hiding this comment.
Are you planning to leverage https://issues.redhat.com/browse/WFLY-17651 for these instructions?
With https://issues.redhat.com/browse/WFLY-18428, we want to have a user being able to get up and running with WildFly in a few minutes. This is achievable by using a Maven archetypes that will do all this plumbing for them.
There was a problem hiding this comment.
No, the idea was to start with the standard Maven archetypes, and document the changes needed. The main reason for this is that WildFly archetypes are not supported, but I also thought of aligning with Quarkus, and reuse their enhancements on app development, both the online tool and the cli app project generation by maven plugin.
There was a problem hiding this comment.
WildFly archetypes are not supported
We have been providing them and maintaining them. I don't see why we could not use them to bootstrap the necessary Maven project.
I can do a mvn archetype:generate and starts writing my code in a matter of minutes. Why would I start from scratch and spend 1/2 to 1 hour just to have the pieces in place in the pom.xm, src/main & src/test?
There was a problem hiding this comment.
We have been providing them and maintaining them. I don't see why we could not use them to bootstrap the necessary Maven project.
Because that means we need to make archetypes a product and support it for 10 years, please remember this is the upstream for a new EAP 8 requirement.
I can do a mvn archetype:generate and starts writing my code in a matter of minutes. Why would I start from scratch and spend 1/2 to 1 hour just to have the pieces in place in the pom.xm, src/main & src/test?
Nobody wants to start from scratch, for now use the standard Maven archetypes, next use whatever is best in the long term, if possible aligned with Quarkus (which AFAIK opted for a Maven Plugin instead of archetypes).
There was a problem hiding this comment.
Please note that this doesn't mean we can not add WildFly Archetypes in the upstream guide too, we just need to not make the guide work around it since it's not supported. For instance we can document the supported way and then add a section introducing WFLY Archetypes, and how it automates what we first did manually (add plugin and dep management, import boms, etc.)
There was a problem hiding this comment.
@jmesnil You will find it in the READMEs of several MP Quickstarts, e.g. https://github.com/wildfly/quickstart/blob/a3b0be1576e2cdb93abdb8512074af5006f8e825/microprofile-config/README.adoc?plain=1#L56
There was a problem hiding this comment.
thanks (and that's exactly all the cp and mkdir that I was talking about to fill the general maven archetypes with the specifities of WildFly)
There was a problem hiding this comment.
Which mkdir or cp you referring to?
There was a problem hiding this comment.
all the xml snippets you have to copy to the pom.xml, the directories and files you create to populate src, etc.
There was a problem hiding this comment.
The only non-app-specific are the pom.xml changes there that I previously referred, which have little time/effort impact due to the need for app-specific changes there too, e.g. dependencies.
| *** How to build, deploy and run on Openshift (basic usage) | ||
|
|
||
| * The major section for first time app developers should also include the following new content: | ||
| ** How to develop a first basic application for each specific supported component/technology (e.g. CDI) |
There was a problem hiding this comment.
Are you planning to modularise that content? How would you sort/present the sections?
There was a problem hiding this comment.
IMHO these would fit nicely as independent modules/guides, which could even be external to the document.
|
|
||
| * The major section for first time app developers should also include the following new content: | ||
| ** How to develop a first basic application for each specific supported component/technology (e.g. CDI) | ||
| *** Introduction to the component/Technology |
There was a problem hiding this comment.
Having a list of prerequisites (in terms of tooling or previous guides)
| ** How to develop a first basic application for each specific supported component/technology (e.g. CDI) | ||
| *** Introduction to the component/Technology | ||
| *** Extends the basic application development content (e.g. add needed Maven dependencies related with component/technology) | ||
| *** Any other basic level content which may be useful with respect to the technology |
There was a problem hiding this comment.
Links to relevant sections in WildFly admin guide and model reference for further information
| ** Specific component/technology content (e.g. CDI) | ||
|
|
||
| * The specific content/technology content from the existent Quickstart Guides should be adapted and included in the Advanced app developers section, with respect to the Specific component/technology content. | ||
|
|
There was a problem hiding this comment.
Will it cover migration like the current developer guide does? https://docs.wildfly.org/29/Developer_Guide.html#How_do_I_migrate_my_application_from_AS7_to_WildFly
There was a problem hiding this comment.
I think that we should definitely provide high level migration content, and port the EAP migration guide to upstream.
|
@darranl @jmesnil FYI there is a major rework of the plans for this doc wrt schedule, with a severe reduction of what the doc will cover on first release, targeting EAP 8 GA. Please note that the same content is planned, we are simply moving many parts of it to nice-to-have requirements, which will come post GA, due to schedule limitations. |
emmartins
force-pushed
the
WFLY-15746
branch
from
9bb2388 to
057b5cd
Compare
|
It's hard to review the AD when it's aiming to EAP Development Guide whereas being located in WFLY proposals. I've already seen the preview version of this guide, LGTM due to the fact it only contains necessary hard requirements since all previous hard requirements were moved to nice-to-have section. Having said that, there is no many things to review, but I'll leave the possibility of making the final conclusion to Krystof Stekovic. |
|
@zhantemirov fyi there is now an upstream PR too, did review it today live with Ashwin... so we will follow the standard process and this won't be EAP only any longer. |
|
Thanks @zhantemirov for your review. I don't have more to say. This proposal LGTM. |
|
thanks @zhantemirov @kstekovi for the review |
Issue: https://issues.redhat.com/browse/WFLY-15746