Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [starter-dev] Starter archetypes / GUI / Issue #67
The issue is that navigating options via Maven filtering is very far from easy, as compared to using a UI. That’s why we need to introduce the need for that layer with some caution. That’s not to say it’s altogether avoidable. It certainly would be the solution if we have to have different Archetypes for significantly different code generation capabilities.

This is the full text you were referring to for reference:

“Within the Maven project, we use archetypes to try and get our users up and running as quickly as possible by providing a sample project that demonstrates many of the features of Maven, while introducing new users to the best practices employed by Maven. In a matter of seconds, a new user can have a working Maven project to use as a jumping board for investigating more of the features in Maven.”

If you notice, there is a clear theme of being oriented to new users and illustrative samples to help get started, not merely providing minimal project bootstrap code like the Spring, Quarkus, etc starters do,

I suggest looking at things like the Azure Functions Archetype a bit closer. Much like what we have done for the REST CRUD example, it also provides complete working examples including non-trivial configuration and unit/integration testing. We have done extensive user studies on this approach and the reaction is overwhelming positive from newcomers. I have really no doubt this is a capability we need to bring into the Jakarta EE starter experience to increase adoption for the technology.

With regards to embedded databases, I suggest looking at what the Spring initializer and getting started samples do with H2. The reason that is done is because it provides for a very nice getting started experience right from the command line and Maven in a self-contained fashion. The alternative is to introduce the need for Docker right away. Unfortunately there are many (perhaps the majority) for whom Docker from the get-go is just too much. In Azure for example, only about a third of our customers are Docker savvy still. As a result, being too dependent on Docker risks becoming a usability hassle, especially for newcomers.

I definitely do encourage you to take some time to explore and think about what is there at the moment. I would also encourage looking at some of the very nice work people in the ecosystem have been doing for some time: https://www.andygibson.net/blog/projects/knappsack/. With the Eclipse Foundation move, we can finally try to make some of this official. Some acclimation is a natural part of onboarding into any new effort with non-trivial existing content/contributors. Likewise I will also carefully take a look at what you have and try to come up with a fair approach of how we could merge efforts without too much disruption to the folks already contributing, some for a long time now.

From: starter-dev <starter-dev-bounces@xxxxxxxxxxx> on behalf of Ivo Woltring <ivo@xxxxxxxxx>
Sent: Tuesday, May 3, 2022 2:57 AM
To: starter developer discussions <starter-dev@xxxxxxxxxxx>
Subject: Re: [starter-dev] Starter archetypes / GUI / Issue #67
 
You might be right on the solo effort. I have no experience with the collaboration on a large scale yet, so I’ll take your word for it.
I can only speak from my experience and the reasons I do things and why I like things.

Actually I am very much an IDE / Command-line person. The reason I created a UI was just for convenience and to learn a new front-end language and give myself a useful project to learn it on 😄. Oh and it might help others too...

I actually do not agree with with the commandline easier to use with less to navigate. Right now there are some 3091 archetypes in the standard list of archetypes if you just run "mvn archetype:generate”. That already make navigating a chore. So if you document that you can easily find all the relevant archetypes for jakartaee with a command like "mvn archetype:generate -Dfilter=org.eclipse.starter:” and you have a very good naming convention the list should be beautiful and completely comprehensive.

If you look at this site https://maven.apache.org/guides/introduction/introduction-to-archetypes.html it actually says nothing about that it is meant for newcomers it  only says: “...while introducing new users to the best practices employed by Maven. In a matter of seconds, a new user can have a working Maven project to use as a jumping board....”  (quoted)
- A jumping board is not the same as a fully fletched example
- Best practices is also one that jumps out… If that is the goal then an embedded DB in the archetype while running in an application server does not seem to me as promoting a best practice. 

When I look at https://github.com/microsoft/azure-maven-archetypes I actually see multiple archetypes with their own life-cycle. The only difference with my idea is that they are maintained in the same repository 😄. The only reason I was going for more repositories is that I am used to having a repository do one thing and only one thing. So I would use a repo for every archetype. I am fully on board if the wish is to maintain them in one repo.

I have a lot to think about again, thanks

Ivo.


On 2 May 2022, at 22:01, Reza Rahman <reza_rahman@xxxxxxxxx> wrote:

I'll take a look and share my thoughts on what you have.

I suspect the primary issue is the amount of generated code and the fact that you might be largely a solo effort and this effort already needing to collaborate between a number of committers and contributors. For solo efforts with very minimal archetypes the complexity that arises from code duplication and needing to maintain multiple archetypes and repositories is less of an issue. I think if you explore the current code base a bit more, you'll see why a simple change like adding a new runtime, fixing a bug or making enhancements across needlessly duplicated code would be a headache across a distributed team.

It also sounds like the command line and IDE usage as opposed to UI usage may not be a primary concern for you. The reason we went the Archetype route (which was not the original direction) is to better enable command line and IDE usage. Having fewer Archetypes to navigate makes the command line and IDE pathways easier to use and document.

One of the prime target audiences we have been putting in efforts towards is newcomers to Jakarta EE (hence start.jakarta.ee). For these sorts of folks there is definite value to a compete working but still relatively small example that showcases the power and simplicity of the platform. This is a primary use case for Archetypes (https://maven.apache.org/guides/introduction/introduction-to-archetypes.html) and there are plenty of examples of this in the Apache Archetype catalog. Certainly this is what we do for our Azure Archetypes (https://github.com/microsoft/azure-maven-archetypes) and it is very much appreciated by newcomers.

That said, another use case is definitely minimal archetypes that just generate a POM. The question is whether that's a valuable model for Jakarta EE. It certainly makes clearer sense for something like Spring, Quarkus or even MicroProfile where the POM itself is not so simple to compose.

With regards to the items on the issue list, they are quite dated and probably should be thought of as long term wish list items at this point rather than an actual committed roadmap. As we begin to tackle those after we work through the roadmap items there are higher levels of commitment on delivering (https://github.com/eclipse-ee4j/starter#roadmap), we would certainly evolve, perhaps logically in the direction of multiple Archetypes. I think for now focusing too much on those does not make sense yet (as opposed to say creating a UI, supporting more popular runtimes or adding support for Jakarta EE 9.1).

For GlassFish questions, please feel free to reach out to the GlassFish alias: https://accounts.eclipse.org/mailing-list/glassfish-dev. Most folks here are not GlassFish committers unfortunately.

On 5/2/22 3:03 PM, Ivo Woltring wrote:
The thing is I have maintained a couple of archetypes the last couple of years and I have chosen to do that in separate repositories because of the ease of use, maintaining and ease of creating new ones. My post processing script is very simple and always the same. 

@Reza you asked for code...

The code for these archetypes can be found here:

And they are all presented (GUI) here:

I hope that is enough of a demonstration of giving clear names and easy code. 

Why would having multiple repositories make maintaining something more difficult? I do not see that at all. If you need to change something for a specific archetype you only have to do that for that archetype right? No other archetypes needs to change. Also if you write a GUI like mine you actually have to document less as the choices you have are already clearly defined in the GUI. The GUI is dead simple because all the archetypes follow the same routine but with a different combination of tools. The telling names say it all.

So in my experience it is way easier to maintain a very simple archetype than to maintain a difficult one. The more the post processing script has to do the more difficult it will become. Taking versions / incompatibilities / different examples / etc. into account.

Right now I am creating an archetype for Glassfish 6.2.5 with JakartaEE 9.1 and Docker.
That is the only thing I want in that archetype. It is almost trivial for me to make a new one based on another example I already have or update that one to the new version, but it is not as trivial for me to create a PR on the official repo and that is why I haven’t yet.

I see a lot of requests for examples in the issue list (https://github.com/eclipse-ee4j/starter/issues). The more examples you are going to put in the more exception flows (lots of if statements) you need to write if you want to jam that al into one repo. It is fantastically easy to create all those examples in separate archetypes and maintain them as they grow or need a new version. 

On another note. Should a fully fletched demo be put into an archetype? If I have to remove 80% of the code every time I need to start a new project I will not use it. How about you? Should examples not be tutorials with a repo attached?

Archetypes are there to generate a specific starting point for developers right? I know I am new to this discussion but if the goal is newcomers isn’t an archetype not a strange approach? I am not trying to be difficult but I honestly don’t understand these choices. I think an archetype should help developers to start coding, not to give a demo.

BTW why do we not have official Glassfish docker images anymore?



On 2 May 2022, at 15:21, reza_rahman@xxxxxxxxx wrote:

The GitHub Actions Pipeline in the current project is already designed to test out all the current options per check-in or PR. Have you had a chance to look at that? Whatever the project structure, it would be important to have such automation in place. I would say these needs are basically the same no matter what the approach.

As I alluded to elsewhere, I personally have a hard time understanding what the value proposition would be for a very basic Archetype for Jakarta EE. Because of the nature of Jakarta EE, the essential Maven structure is always rather simple. Would it really differ very much from the Archetypes that Apache already has in the catalog? Other than the Maven project structure and POM, what other generated code would be included if any? A Servlet or JSF page? Is that really important these day? A REST endpoint? Is that really different enough from what’s there right now?

Anyway, a relatively complete code example of what would be generated would really help me understand (and probably others too). How do you think one could get that? Would it be possible to issue a draft PR? Is it already available to see? That would also help clarify the value for a possible separate Archetype (that’s what I had in mind for JSF as the generated code including the unit tests and index page would likely vary too much from the current REST CRUD example).
 
From: starter-dev <starter-dev-bounces@xxxxxxxxxxx> on behalf of Ivo Woltring <ivo@xxxxxxxxx>
Sent: Monday, May 2, 2022 3:07 AM
To: starter developer discussions <starter-dev@eclipseorg>
Subject: Re: [starter-dev] Starter archetypes / GUI / Issue #67
 
If you make an archetype that can do a lot of things and configure a lot then it becomes more difficult by definition.
How do you test such an archetype with all its options? Generate all combinations with every change and see if it still works?

DRY is in my opinion not always the best way to go, but I see your point.

What of a compromise?

A bare bones project with only the maven project and Dockerfile of choice and one with all the demo thingies and options in it.
One for new blood to learn and one for those who just want a new project so they can start jamming?




On 1 May 2022, at 08:03, reza_rahman@xxxxxxxxx wrote:

So I had a quick side chat with some of the folks that develop our various Maven Archetypes for Azure just to validate what I had been planning. They confirmed that this is not just doable but very normal for what is typically done in post-processing scripts for non-trivial Archetypes. Indeed it is rather simple compared to much more advanced capabilities like in this example script they shared: https://github.com/microsoft/azure-maven-archetypes/blob/develop/azure-functions-archetype/src/main/resources/META-INF/archetype-post-generategroovy. This is the use cases that post processing scripts are for after all as opposed to the more basic Archetype templating features.

Still, I am happy to actually prototype out what I had in mind so folks here can take a look and hopefully see for themselves how much not a big deal this really is.

Now, I am not saying that if the generated project varies too much in reaction to parameters that there isn’t a sensible case for creating a separate Archetype. For example, I can see a generated JSF CRUD project being sufficiently different from the current REST CRUD generated code. But fairly minor variations for Jakarta EE versions and target platform? I think that’s no big deal at all. Even the relatively simple Payara Micro Archetype handles Jakarta EE versions just fine as parameters: https://docs.payara.fish/enterprise/docs/documentation/ecosystem/maven-archetype.html.
 
From: reza_rahman@lycoscom <reza_rahman@xxxxxxxxx>
Sent: Saturday, April 30, 2022 8:14 AM
To: starter developer discussions <starter-dev@xxxxxxxxxxx>
Subject: Re: [starter-dev] Starter archetypes / GUI / Issue #67
 
I have to be honest, I really don’t see why multiple Archetypes would be any easier at all for anyone.

From one Jakarta EE version to another, the only things that would change are Jakarta EE dependency versions, Java SE versions, runtime versions and package names. Those could easily be expressed as variables in the source and filled out using templates in the Groovy post-script (Groovy even has built-in template engines for this). The user simply needs to specify the Jakarta EE version as an Archetype parameter. The Groovy post script can then easily replace a set of variables depending on the user input parameter. This of course in addition to the incremental file replacement technique we already have in the Groovy script. These simple techniques avoid needless complexity for the end user and code duplication while utilizing reasonable modularization.

Before going down the multiple Maven Archetypes road, I suggest taking a look at how that would work. It’s really quite simple, flexible and robust. I can dynamically generate just the Java/Jakarta EE package name for now to demonstrate the technique if you like. I’ll need about a weekend’s time to do that if this is a priority right now.
 
From: starter-dev <starter-dev-bounces@xxxxxxxxxxx> on behalf of Ivar Grimstad <ivar.grimstad@xxxxxxxxxxxxxxxxxxxxxx>
Sent: Saturday, April 30, 2022 2:03 AM
To: starter developer discussions <starter-dev@xxxxxxxxxxx>
Subject: Re: [starter-dev] Starter archetypes / GUI / Issue #67
 
We need to be able to support multiple versions of Jakarta EE at the same time. 
Support for EE 9 and EE 10 is crucial to get out ASAP. For this we have two options:

1. One archetype that supports the generation of multiple Jakarta EE versions
2. One archetype per Jakarta EE version

I think that 2) will get us there faster, and also reduce the complexity of the archetype. Thus apply WET rather than DRY. It would also be clear for the user which version is being generated by this being reflected in the maven coordinates. For example:

org.eclipse.starter::jakartaee8
org.eclipse.starter::jakartaee9
org.eclipse.starter::jakartaee10
...

Ivar




On Fri, Apr 29, 2022 at 9:41 PM Reza Rahman <reza_rahman@xxxxxxxxx> wrote:

Certainly a welcome idea, though hopefully not an "as-is" donation but a merge?

For example, are separate Archetypes really needed? I think for folks using it from the command line and IDE, just one Archetype would be far easier. As such, it is very easy to modularize Archetypes instead of exposing the user to the complexity of multiple Archetypes I think (you can hopefully see that in the code currently in the main branch and various runtime support).

On 4/29/22 3:06 PM, Ivo Woltring wrote:
Hi y’all,


A Couple of weeks ago I was triggered by the new https://start.jakarta.ee/ archetype and have been playing with it.

The last couple of years I have maintained a couple of javaEE/jakartaEE maven archetypes and exposed them to the web: https://ivonet.github.io/archetype/
Just now I saw the issue created by Ivar https://github.com/eclipse-ee4j/starter/issues/67 and that made me think.

If the community is open to it, I would love to join the effort and possibly ”donate" all my archetype related material.
It is already open source but right now under the Apache2 license. That is also open to change as I am the sole committer on these projects.

Please let me know what you think.

Kind regards,

Ivo Woltring.

@ivonet



_______________________________________________
starter-dev mailing list
starter-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://dev.eclipse.org/mailman/listinfo/starter-dev
_______________________________________________
starter-dev mailing list
starter-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://dev.eclipse.org/mailman/listinfo/starter-dev


--
Ivar Grimstad
Jakarta EE Developer Advocate | Eclipse Foundation Eclipse Foundation - Community. Code. Collaboration. 
_______________________________________________
starter-dev mailing list
starter-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://dev.eclipse.org/mailman/listinfo/starter-dev

_______________________________________________
starter-dev mailing list
starter-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://dev.eclipse.org/mailman/listinfo/starter-dev


_______________________________________________
starter-dev mailing list
starter-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://dev.eclipse.org/mailman/listinfo/starter-dev
_______________________________________________
starter-dev mailing list
starter-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://dev.eclipse.org/mailman/listinfo/starter-dev

Back to the top