Huge +1 to proper release notes, which may make sense as blog posts as well as the email announcement.
Yes, we have the Jira "release notes," but they are only one step above the git commit logs, and generally hard to digest (especially for an outsider). For example, if I go to https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12319527&version=12341608 the first thing I see is a list of context-less "sub-tasks," and nowhere is it explicitly stated that we removed Spark 1.x in favor of Spark 2, and the fact that Java 7 was removed is only implied by some of the subtasks (both really big things that should be called out). Significant user-facing features like "Add support for S3 as a Apache Beam FileSystem" are mixed in with less obvious ones like "Java FnApiDoFnRunner to share across runners" and "support View.CreatePCollectionView in FlinkRunner" in a big wall of text (which is a good show of activity, but not much in the way of a compelling reason to upgrade or what to keep an eye on when you do). Sure it deserves a call out as "here are all the bugs we fixed" but that's not a replacement for a good set of release notes itself. That being said, curating and composing a proper set of release notes can be a time consuming process. The only way I've seen this successfully and regularly done without placing an undue burden on the release manager (that already has a high task) is having a running "release notes" doc in the repository itself that gets added to whenever significant features (or changes) get implemented (possibly at the request of the reviewer). The goal is not to be comprehensive, but a ~one-page summary of what someone would care about in this release. - Robert On Fri, Feb 16, 2018 at 2:06 PM, Eugene Kirpichov <kirpic...@google.com> wrote: > Thanks Ismael - I've added a couple of the major things I know. I tried > scanning the whole git shortlog for major things, but it was too much, so > probably better if individual committers make their contributions to the > document. > > On Fri, Feb 16, 2018 at 9:01 AM Ismaël Mejía <ieme...@gmail.com> wrote: >> >> As discussed in this thread I created an initial version of a document >> for the release notes. >> Feel free to add/include details that you consider worth (+correct my >> english mistakes) or new sections/ideas. >> Remember the idea is to have a concise document of the most important >> changes in this release. >> I will migrate this into proper markdown for a blog post about the >> release is deployed into maven central. >> >> >> https://docs.google.com/document/d/1_fpD6E2XYPzjndHaoT0AVSWijUyHCMczZhUyAHUt7bk/edit?usp=sharing >> >> >> On Mon, Jan 29, 2018 at 6:43 PM, Jean-Baptiste Onofré <j...@nanthrax.net> >> wrote: >> > Agree, and 1/ should already be part of the announcement e-mail (at a >> > very high >> > level). >> > >> > Regards >> > JB >> > >> > On 01/29/2018 06:41 PM, Daniel Kulp wrote: >> >> Personally, I would like to see two things: >> >> >> >> 1) A “shortish” announcement blog post that describes at a very high >> >> level the new things. This really can just be the release notes. >> >> >> >> 2) If there are big “really cool” things that deserve more attention >> >> (and a developer willing to give it said attention), some follow up blog >> >> posts in the weeks after the release describing those new features, >> >> providing examples, etc…. Kind of a “deeper dive”. “2.4.0 introduced >> >> Schema Aware PCollections, what are they and why should you care?” Kind of >> >> thing. This would be completely optional (#1 is more important) and up >> >> to the devs, but it could be a good way to get more folks really reading >> >> the >> >> blog and getting folks interested in what’s going on and such. >> >> >> >> >> >> Dan >> >> >> >> >> >>> On Jan 29, 2018, at 9:02 AM, Jean-Baptiste Onofré <j...@nanthrax.net> >> >>> wrote: >> >>> >> >>> Hi Ismaël >> >>> >> >>> The idea is good, but the post should be pretty short. Let me explain: >> >>> >> >>> - We will have a release every two months now, so, some releases might >> >>> be >> >>> lighter than others, and it's normal >> >>> - the Jira Release Notes already provides lot of details >> >>> >> >>> For instance, in Apache projects like Karaf, Camel, and others, we do >> >>> the >> >>> announcement of a release on the mailing lists with the release notes >> >>> linked. >> >>> Sometime, we do a blog to highlight some interesting new features, but >> >>> it's not >> >>> systematic. >> >>> >> >>> So, I agree: it's a good idea and I would give some highlights about >> >>> what we are >> >>> doing and where we are heading. However, I don't think we have to >> >>> "enforce" such >> >>> blog post for every single release. It's a best effort. >> >>> >> >>> My $0.01 ;) >> >>> >> >>> Regards >> >>> JB >> >>> >> >>> On 01/29/2018 02:47 PM, Ismaël Mejía wrote: >> >>>> This is a fork of a recent message I sent as part of the preparations >> >>>> for the next release. >> >>>> >> >>>> [tl;dr] I would like to propose that we create a new blog post for >> >>>> every new release and that this becomes part of the release guide. >> >>>> >> >>>> I think that even if we do shorter releases we need to make this part >> >>>> of the release process. We haven’t been really consistent about >> >>>> communication on new releases in the past. Sometimes we did a blog >> >>>> post and sometimes we didn’t. >> >>>> >> >>>> In particular I was a bit upset that we didn't do a blog post for the >> >>>> last two releases, and the list of JIRA issues sadly does not cover >> >>>> the importance of some of the features of those releases. I am still >> >>>> a >> >>>> bit upset that we didn't publicly mentioned features like the SQL >> >>>> extension, the recent IOs, the new FileIO related improvements and >> >>>> Nexmark. Also I think the blog format is better for ‘marketing >> >>>> reasons’ because not everybody reads the mailing list. >> >>>> >> >>>> Of course the only issue about this is to decide what to put in the >> >>>> release notes and who will do it. We can do this by sharing a google >> >>>> doc that everyone can edit to add their highlights and then reformat >> >>>> it for blog publication, a bit similar to the format used by Gris for >> >>>> the newsletter. Actually if we have paced releases probably we can >> >>>> mix >> >>>> both the release notes and the newsletter into one, no ? >> >>>> >> >>>> What do you think? Other ideas/disagreement/etc. >> >>>> >> >>> >> >>> -- >> >>> Jean-Baptiste Onofré >> >>> jbono...@apache.org >> >>> http://blog.nanthrax.net >> >>> Talend - http://www.talend.com >> >> >> > >> > -- >> > Jean-Baptiste Onofré >> > jbono...@apache.org >> > http://blog.nanthrax.net >> > Talend - http://www.talend.com
