First, huge thank you for putting effort into ensuring the release notes are clear! It's an under appreciated and usually thankless job. However, communicating change on a new major version is critical and you just get one chance to build excitement.
> On Aug 28, 2018, at 9:02 AM, Roberto Cortez <radcor...@yahoo.com.INVALID> > wrote: > > Hi, > > I’m trying to compile a list of things regarding the TomEE 8 Release. Right > now, this is our preview for the Release Notes from JIRA: > > Bug My memory is perhaps off, but I thought bugs came after New Features and Improvements on the generated release notes. If they haven't in the past, we should likely do that for this one. > • [TOMEE-2206] - Support for Enum injection in Microprofile JWT I think this is an improvement vs bug. Perhaps even moved to tasks. It's always been a stance of the project that unreleased features can't have bugs. The intent of Bug is to communicate "you may have encountered this in a previous release and it is now fixed." We want user's to be able to rely on this meaning. It's natural to want to do it, but here's how I was able to convince myself it wasn't the right thing. This usage of "bug" essentially means, "We noticed we weren't quite as done as we thought after the first commit of this feature. It's never been released so you could never have encountered it in production and if you are alarmed by it or hopeful it solves a problem you had, that'd be silly of you. It's just an ignorable note that we had to continue working on the feature longer than we thought, considerately mixed in with critical things that affect your daily life." Once that thought entered my brain, it started changing neural pathways and I've been unable to get rid of it. Joking aside, the result for users is that our release notes start to become a puzzle of potential misinformation. > New Feature > • [TOMEE-2209] - MicroProfile 1.2 Support > • [TOMEE-2210] - MicroProfile 1.3 Support > • [TOMEE-2211] - MicroProfile 1.2 Support - Configuration 1.1 > • [TOMEE-2212] - MicroProfile 1.2 Support - Fault Tolerance 1.0 > • [TOMEE-2213] - MicroProfile 1.2 Support - JWT Propagation 1.0 > • [TOMEE-2214] - MicroProfile 1.2 Support - Health Check 1.0 > • [TOMEE-2215] - MicroProfile 1.2 Support - Metrics 1.0 > • [TOMEE-2216] - MicroProfile 1.3 Support - Config 1.2 > • [TOMEE-2217] - MicroProfile 1.3 Support - Metrics 1.1 > • [TOMEE-2218] - MicroProfile 1.3 Support - Rest Client 1.0 > • [TOMEE-2219] - MicroProfile 1.3 Support - Open API 1.0 We should yank the duplicate entries and just talk net-net. People can assume Configuration 1.2 also includes 1.1 and 1.0. If we completely implement MicroProfile 1.3, we can say that and not mention 1.2. If we do not fully implement MicroProfile 1.3, the above didn't help me understand the status. On the individual MicroProfile specifications, I would not refer to them as "MicroProfile 1.3 Support - Config 1.2", but simply "MicroProfile Configuration 1.2" - It will search better in Google - Some specs like Metrics 1.0 are in MP 1.2 and 1.3. Showing it as "MP 1.2" could mean it was introduced in 1.2 and hasn't changed in 1.3. It could mean Metrics is at 1.1 in MP 1.3, but we don't implement it yet. It could mean Metrics was removed entirely in MP 1.3 so we only mention it as a MP 1.2 feature. Unless you know enough not to need the release notes, you won't know which. You're right in that we need a complete list of other new features, particularly our complete Java EE 8 status has to be listed here as well. > Improvement > • [TOMEE-2195] - Compile Error in > /src/main/java/org/apache/openejb/config/AnnotationDeployer We should probably move that one to tasks. > • [TOMEE-2196] - keyStoreFile Property is Empty in Embedded Container > • [TOMEE-2221] - Use a Jsonb aware JAX-RS Provider > • [TOMEE-2222] - Enable create-tables for EclipseLink in Moviefun > example > • [TOMEE-2224] - update to apache-parent-21 for sha512 Picky I know, but we should change the case on this description to be consistent. Also, it should be in upgrades technically. > Task > • [TOMEE-2159] - TomEE8: JSF 2.3 > • [TOMEE-2160] - TomEE8: Servlet 4.0 These two should go to new features. We should also yank the "TomEE8:" prefix. > • [TOMEE-2174] - Nested parameters prevent EJB interceptor matching This sounds like it should go to bug. > Dependency upgrade > • [TOMEE-2171] - Upgrade to ActiveMQ 5.15.3 > • [TOMEE-2178] - TomEE8: Update to MyFaces 2.3.0 release > • [TOMEE-2179] - tomcat 9.0.8 > • [TOMEE-2180] - johnzon 1.1.7 > • [TOMEE-2184] - MyFaces 2.3.1 > • [TOMEE-2186] - Upgrade CXF to 3.2.4 > • [TOMEE-2187] - Upgrade to XBean 4.9 > • [TOMEE-2207] - Update Bouncy Castle to 1.60 We should update all the titles to be consistent in use (or non use) of "Upgrade" and how they are phrased. Small detail, but shows we care. > Additionally, we have the following issue list associated to TomEE 8, that we > need to update or decide if we need to do something with them for this > release: > • [TOMEE-2115] - TomEE-8 work Commits with this JIRA might help us find work that should get its own JIRA and be mentioned in the release notes. This item might possibly be a good candidate to retitle "Java EE 8 Support" > • [TOMEE-2116] - Create javaee-api-8.0.0 Good one for the notes, but cleaned up. > • [TOMEE-2117] - Rework ProcessObserverMethod integration > • [TOMEE-2139] - org.apache.tomee.jul.handler.rotating.ArchivingTest > broken in 2nd iteration > • [TOMEE-2140] - retire or fix arquillian-jpa example We should figure out which way we went on this and update the title. > • [TOMEE-2169] - Interceptor Bean injection does not work for EJBs This sounds like a bug. > • [TOMEE-2185] - Add MP-JWT support We should yank the duplicates like "Add MP-JWT support" and mark them duplicates (or mark the newly created TOMEE-2213 as a duplicate of TOMEE-2185, then update the title of TOMEE-2185). > • [TOMEE-2227] - upgrade CXF to 3.2.6 and tomcat to 9.0.11 We need to update the respective "Upgrade" issues and mark this as duplicate. We should of course check the actual version of Tomcat and CXF to ensure it's accurate. We've got on saying Tomcat 9.0.8 and other saying 9.0.11. Let's hope it's 9.0.11 :) > • [TOMEE-2197] - openejb.xml <Deployments jar="..."/> does not work This sounds like a bug and it sounds like an overstated bug that needs more context on the subject. > Also, I guess that a lot of work was done without creating issues, so > everything that was done is not completely reflected in this list. We may > need to create some issues for that. For a bit I attempted to be extremely diligent with making release note entries for old commits. At one point I even hacked up a bit of code to help me review each individual commit. - https://svn.apache.org/repos/asf/tomee/sandbox/release-tools/src/main/java/org/apache/openejb/tools/release/cmd/ReviewCommits.java It was basically a shell that pulled all the svn commit logs in xml format and then looped you over each one and you could hit the V, A, N, or C keys to View the jira, Associate the commit with a jira, skip to the Next commit, or Create a jira for the commit and associate it. I don't know what the heck I was on. :) You definitely do not have to do that. -David
