On Mon, Feb 3, 2020 at 2:09 PM Robert Bradshaw <rober...@google.com> wrote:

> I would suggest we start with the simpler single file. If merge
> conflicts become an issue, we could look at other options, but I think
> it's worth keeping in mind that what we're trying to produce here is a
> single, higher-level, cohesive summary of the release rather than a
> 1:1 listing of commits, pull request, or jira entries (which we can
> link to). While new features often merit their own bullet points, this
> will allow for entries such as "Several improvements to portability
> including ..."
>

I agree. If there are no objections I will go ahead with the PR I proposed.
It adds a single change log file to begin with.

We would need all committers to help after that by asking PR authors to
update this file whenever it makes sense.


>
> On Mon, Feb 3, 2020 at 1:55 PM Ahmet Altay <al...@google.com> wrote:
> >
> >
> >
> > On Sat, Feb 1, 2020 at 9:22 AM Chad Dombrova <chad...@gmail.com> wrote:
> >>
> >> In case it's of any use, there's a tool called towncrier[1] to help
> compile changelog fragments and compile them at time of delivery.
> >
> >
> > I would prefer not to have the complexity of multiple files and an added
> tool to the release process. I do not have a strong opinion though. If
> others prefer we can switch to this tool. One nice benefit of this tool
> would be to avoid merge conflicts if many different PRs edit the change log
> file all at the same time in a conflicting way.
> >
> >>
> >>
> >> I came across this when working on the python-attrs[2] project, which
> has some good documentation for contributors on how to use it:
> https://www.attrs.org/en/stable/contributing.html#changelog
> >>
> >>
> >> [1] https://github.com/hawkowl/towncrier
> >> [2] https://github.com/python-attrs/attrs
> >>
> >>
> >> On Fri, Jan 31, 2020 at 5:09 PM Ahmet Altay <al...@google.com> wrote:
> >>>
> >>> Thank you for the quick responses. I sent out
> https://github.com/apache/beam/pull/10743 to make this change. Please
> provide feedback or directly edit the PR.
> >>>
> >>>
> >>> On Fri, Jan 31, 2020 at 3:58 PM Robert Bradshaw <rober...@google.com>
> wrote:
> >>>>
> >>>> Yes, yes, yes! This is the one model of release notes that I've
> >>>> actually seen work well at scale.
> >>>>
> >>>>
> https://lists.apache.org/thread.html/41e03ace17dbcccf7e267ba6d538736b2a99a8e73e7fb45702766b17%40%3Cdev.beam.apache.org%3E
> >>>>
> >>>> Let's make it happen.
> >>>>
> >>>> On Fri, Jan 31, 2020 at 3:47 PM Robert Burke <rob...@frantil.com>
> wrote:
> >>>> >
> >>>> > I like this suggestion, Jira titles and commit summaries don't
> necessarily reflect the user impact for a given change (or set of changes).
> Being able to see the Forest instead of the trees.
> >>>> >
> >>>> > On Fri, Jan 31, 2020, 3:37 PM Kenneth Knowles <k...@apache.org>
> wrote:
> >>>> >>
> >>>> >> +1
> >>>> >>
> >>>> >> This is a great idea. Hope it can lead to higher-value view of
> relevant changes.
> >>>> >>
> >>>> >> I like it being in the root of the repo, so it lives next to the
> code.
> >>>> >>
> >>>> >> Since the website is also markdown, it could be copied over
> directly at release time, so it can be browsed there, too.
> >>>> >>
> >>>> >> Kenn
> >>>> >>
> >>>> >> On Fri, Jan 31, 2020 at 3:16 PM Ahmet Altay <al...@google.com>
> wrote:
> >>>> >>>
> >>>> >>> Hi all,
> >>>> >>>
> >>>> >>> We currently have two major ways to communicate changes in a
> release:
> >>>> >>> - A blog post, to highlight major changes in the release.
> (Example for 2.17: [1])
> >>>> >>> - JIRA release notes pages listing all issues tagged for a
> specific release. (Example for 2.17 [2]).
> >>>> >>>
> >>>> >>> There are a few issues with this process:
> >>>> >>> - It is difficult for the release manager to know what is
> important, what is a breaking change, what is dependency change etc. For
> example, there were more than 150 Jira issues tagged for 2.17 release.
> >>>> >>> - Release blog has many items, and does not necessarily
> communicate important changes. It is difficult for users to discover major
> changes short of going through a large list.
> >>>> >>> - People involved in authoring or reviewing a PRs usually have
> the most context about the change, and they are not necessarily involved in
> the release process to provide this additional information.
> >>>> >>>
> >>>> >>> Would it be helpful if we maintain a simple change list file and
> update it as part of the PRs with noteworthy changes? Release managers
> could use this information as is in their blog posts (or link to it). Users
> will have a single place to find highlights from various versions.
> >>>> >>>
> >>>> >>> Concretely, I am proposing:
> >>>> >>> - Adding a CHANGES file to the root of the repository. (Name
> could be anything, TFX uses RELEASE.md in their repo. [3])
> >>>> >>> - Ask PR authors to update this file as part of their PR whenever
> it makes sense
> >>>> >>> - Reference this file during the release process, and a new
> section for the next release after each release.
> >>>> >>>
> >>>> >>> Ahmet
> >>>> >>>
> >>>> >>> [1] https://beam.apache.org/blog/2020/01/06/beam-2.17.0.html
> >>>> >>> [2]
> https://issues.apache.org/jira/secure/ReleaseNote.jspa?version=12345970&projectId=12319527
> >>>> >>> [3] https://github.com/tensorflow/tfx/blob/master/RELEASE.md
>

Reply via email to