Examples setting TomEE version via ${project.version}

[David Blevins <db...@tomitribe.com>]

For many years we intentionally kept examples at a version number different than the TomEE/OpenEJB version.  Most used version 1.0-SNAPSHOT.

The reasons for this is the same reason we don't a parent pom.

 - Each example should be fully standalone
 - Users shouldn't have to "cut it free" from our build structure and struggle

When examples use 1.0-SNAPSHOT (or any other fictitious version) users are setup with a pom as close as possible to a real world setup.  They can change it to any version without consequence.
 
When examples use 8.0.1-SNAPSHOT (or whatever the current TomEE version is) users quickly start seeing examples that tell them they should use `${project.version}` to set the TomEE version.  They need to learn the hard way this isn't true.  They also need to learn on their own to use `${tomee.version}` or some better practice.  If the example has modules in it, they need to be careful not to accidentally change uses of `${project.version}` that are actually necessary.

Similarly, we don't use `org.apache.tomee` as the example package to be clear what you need to change and what you should not change.  When you do change the example package, you're lined up for the highest chance of success.

We have 571 `org.apache` dependency declarations across our 195 examples and did great not using ${project.version} as it was impossible.  We now have 14 uses of `${project.version}` on org.apache dependencies that have crept in.  As we've added about 30 examples in the last year those aren't good odds.

Understood the reason for changing it to the TomEE version was "ease"; this definitely is easier for example creators, but harder for example users.  Also understood these things are not obvious and if you weren't around when we all made this exact mistake in 2008 you didn't get the benefit of being there to learn the hard way with the rest of us :)


Do we want to switch back?


-- 
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com

Re: Examples setting TomEE version via ${project.version}

[Jonathan Gallimore <jo...@gmail.com>]

I have some recollection of it changing at release-time when Mark
kindly did a release. I'd be in favor of resetting these to 1.0-SNAPSHOT
and fixing any release issues.

Jon

On Thu, Oct 24, 2019 at 9:16 AM David Blevins <db...@tomitribe.com>
wrote:

> For many years we intentionally kept examples at a version number
> different than the TomEE/OpenEJB version.  Most used version 1.0-SNAPSHOT.
>
> The reasons for this is the same reason we don't a parent pom.
>
>  - Each example should be fully standalone
>  - Users shouldn't have to "cut it free" from our build structure and
> struggle
>
> When examples use 1.0-SNAPSHOT (or any other fictitious version) users are
> setup with a pom as close as possible to a real world setup.  They can
> change it to any version without consequence.
>
> When examples use 8.0.1-SNAPSHOT (or whatever the current TomEE version
> is) users quickly start seeing examples that tell them they should use
> `${project.version}` to set the TomEE version.  They need to learn the hard
> way this isn't true.  They also need to learn on their own to use
> `${tomee.version}` or some better practice.  If the example has modules in
> it, they need to be careful not to accidentally change uses of
> `${project.version}` that are actually necessary.
>
> Similarly, we don't use `org.apache.tomee` as the example package to be
> clear what you need to change and what you should not change.  When you do
> change the example package, you're lined up for the highest chance of
> success.
>
> We have 571 `org.apache` dependency declarations across our 195 examples
> and did great not using ${project.version} as it was impossible.  We now
> have 14 uses of `${project.version}` on org.apache dependencies that have
> crept in.  As we've added about 30 examples in the last year those aren't
> good odds.
>
> Understood the reason for changing it to the TomEE version was "ease";
> this definitely is easier for example creators, but harder for example
> users.  Also understood these things are not obvious and if you weren't
> around when we all made this exact mistake in 2008 you didn't get the
> benefit of being there to learn the hard way with the rest of us :)
>
>
> Do we want to switch back?
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>