Hi Jason, thanks for bringing this to the table, because I agree that we have to keep an eye on such examples to make them as easier as possible to use.
I see the PR has been closed, anyway I would like to add my 2c. Putting the versions in the properties block, provided they have meaningful names, actually improves readability and maintainability of poms. On one side, this is sort of standard on all our codebase. Besides, it is also sort of standard elsewhere. Third (and the justification of the previous) is that when you put all the "variables" in one single place, you do not need to jump hither and thither to find/replace them, when needed, even if a specific variable is used once. And this is especially true for people that use our code the first time (again, provided the properties have proper names). Let's figure out there is a version upgrade to be done: you simply go to the properties block and it is done. And, if the version upgrade involves multiple libraries, the usefulness of having all of them in one specific place is much clearer. ------ But there is a detail that we may discuss in future, maybe in another thread, about <parent> declarations to make examples self-contained. We took that as an undisputable assumption, but IMO this is a fallacy, because 1. Anyway, the project requires dependencies that are pulled down from maven repository 2. if those dependencies are explicitly declared or inherited, it does not make any real difference For example, when you start a springboot project, from the springboot wizard <https://start.spring.io/>, the project always has a "springboot" parent, and this simplifies things a lot for the user, because the mandatory dependencies are automatically inherited. In our examples, some dependencies are shared between all of them, because those are actually required. But we "force" users to redeclare them in their project (copying the example). And if the user builds a project on top of a given version, and then wants to switch to the next one (s)/he has to go through all of them and update accordingly, time-consuming and error-prone. Again, this would be unneeded if we simply provide examples with parents. Anyway, I just comment here because it has been mentioned before and, IMO, it is one of the assumptions we take for granted but instead we should discuss deeper. Thanks again Jason Best Il giorno gio 8 ago 2024 alle ore 10:38 Francisco Javier Tirado Sarti < [email protected]> ha scritto: > Hi, > I agree that it is better to not use properties for Maven group and > artifactid. > But I hardly understand the argument to not put the kogito version number > as property. This forces you to copy the version number in two different > places within the same file. > For example, here > > https://github.com/apache/incubator-kie-kogito-examples/pull/1988/files#diff-46502ad88658bd0c38baaf5899932513f208505cd38eaf16fe7d9956fd0d3505R44 > and here > > https://github.com/apache/incubator-kie-kogito-examples/pull/1988/files#diff-46502ad88658bd0c38baaf5899932513f208505cd38eaf16fe7d9956fd0d3505R51 > Do we really feel thats an improvement for readability and maintainability? > I asked it twice, really? > Finally, as happened to Roberto, I hardly see the relationship between > changes in the PR and downstream builds. > > On Wed, Aug 7, 2024 at 10:30 PM Tiago Bento <[email protected]> wrote: > > > Hi Jason, thanks for bringing this to the mailing list. My opinion on > > this matter is that it'd be fine both ways (versions on <properties> > > or inline), whatever is easier to keep things working well on PR > > checks and other automations. The important thing, IMHO, is that we > > remove the <parent> declarations to make examples self-contained. > > > > On Wed, Aug 7, 2024 at 3:31 PM Roberto Oliveira > > <[email protected]> wrote: > > > > > > Hi, > > > > > > My comment in the PR was only about not inlining versions from > properties > > > into dependencies. > > > For example the quarkus version (3.8.4) will start to be inlined twice > > > (both for quarkus-bom and quarkus-maven-plugin), while for the property > > it > > > would be defined in a single place, and AFAIK in Maven people tend to > use > > > properties block for most of the dependencies versions. > > > > > > Also I didn't understand why in this thread was mentioned about > > downstream > > > builds, as no one in the PR said anything about downstream builds. > > > But as it was brought up in this thread, yes, we still have a > downstream > > > build which becomes a product, and yes, every release it is becoming > more > > > difficult to build that product due to all changes in the Apache > > community, > > > but again, I don't see any mentions of it in that PR... > > > > > > > > > > > > On Wed, 7 Aug 2024 at 14:22, Jason Porter <[email protected]> > > wrote: > > > > > > > I sent a pull request the other week ( > > > > https://github.com/apache/incubator-kie-kogito-examples/pull/1988) > > which > > > > removes many of the properties in the Kogito Quarkus Examples. It has > > > > sparked some conversation, and I figured instead of talking on the > PR, > > the > > > > mailing list would be a better place to have the conversation. > > > > > > > > Let me start with the reasoning behind this PR. This was done to make > > the > > > > examples easier to understand and easier to use as a starting place > > for new > > > > applications/uses. The examples as they currently exist today, have > > many > > > > properties used in various parts of the pom.xml file. Some of these > > > > properties specify versions, others modify maven plugin settings, and > > still > > > > others specify the group and artifact ids for any downstream > > modifications. > > > > > > > > It is my own opinion that modifying the community project to make it > > > > easier on downstream builds should not happen. If any entity is > taking > > the > > > > community project and building on top of it, it should be up to that > > entity > > > > to make the necessary changes from the community source for their > > usage. > > > > Modifying the community to suite any downstream activity should be > > avoided. > > > > It shows bias toward that entity, and creates an atmosphere of > > exclusion, > > > > which should not happen. > > > > > > > > For anyone coming to our project for the first time, they should > have a > > > > path of least resistance for onboarding. Our examples should be easy > to > > > > use, understand, and modify. There is simplicity in keeping > everything > > in > > > > one file and not having to scroll around looking at what a particular > > > > property is. This also goes for parent poms, but that is a slightly > > > > different discussion. I believe there is value in keeping our > examples > > > > simple. > > > > > > > > The other side of this is the additional maintenance we incur doing > > things > > > > this way. It is certainly easier to only have these properties > defined > > once > > > > and reused in various places. It is also considered best practice by > > many. > > > > I would agree with those as well, for everything besides examples. > > However, > > > > we’re only talking about a hand full of changes, and these can be > > automated > > > > it the build. We’re already doing modifications to pom.xml files > during > > > > builds anyway. It doesn’t add much (any?) additional work beyond what > > we’re > > > > already doing. > > > > > > > > We don’t know the level of people coming to the project for the first > > > > time. They may never have seen an Apache Maven pom.xml file before, > or > > they > > > > may be trying to integrate it into something else which has differing > > > > versions of dependencies. Making these examples easy to understand > > helps > > > > all these people. > > > > > > > > I’ve gathered a small list of different Java based projects to show > how > > > > others do this. Unfortunately, there isn’t a single way everyone does > > this > > > > in their examples, so there isn’t a guiding example for us to follow: > > > > > > > > • > > > > > > > https://github.com/eclipse-ee4j/eclipselink-examples/blob/master/jpa/employee/employee.model/pom.xml > > > > • > > > > > > > https://github.com/eclipse-ee4j/jakartaee-examples/blob/main/applications/kickoff/pom.xml > > > > • > > https://github.com/apache/camel-examples/blob/main/basic/pom.xml > > > > • > > > > > > > https://github.com/apache/activemq-artemis-examples/blob/main/examples/features/ha/application-layer-failover/pom.xml > > > > • > > > > > > > https://github.com/apache/ignite-extensions/blob/master/modules/azure-ext/pom.xml > > > > • > > > > > > > https://github.com/apache/flink/blob/master/flink-examples/flink-examples-batch/pom.xml > > > > • > > > > > > > https://github.com/spring-guides/gs-spring-cloud-loadbalancer/blob/main/complete/user/pom.xml > > > > • > > > > > > > https://github.com/spring-guides/gs-messaging-jms/blob/main/complete/pom.xml > > > > • > > > > > > > https://github.com/spring-guides/gs-spring-boot/blob/main/complete/pom.xml > > > > > > > > --------------------------------------------------------------------- > > > > To unsubscribe, e-mail: [email protected] > > > > For additional commands, e-mail: [email protected] > > > > > > > > > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: [email protected] > > For additional commands, e-mail: [email protected] > > > > >
