We could also create a GitHub label for PRs that should be looked at when crafting the next release notes, applied per committer discretion.
On Fri, Feb 16, 2018, 2:36 PM Robert Bradshaw <rober...@google.com> wrote: > 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 >
