You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@beam.apache.org by Brian Hulette <bh...@google.com> on 2021/09/13 23:01:03 UTC
Release Notes: "Known Issues" or "Fixed Issues"?
Our release notes template [1] contains the following section:
## Known Issues
* Fixed X (Java/Python) ([BEAM-X](
https://issues.apache.org/jira/browse/BEAM-X)).
I find this hard to interpret:
- The title (Known Issues) implies the section is meant to enumerate issues
that we discover in a release after it is too late to fix them.
- The bullet text (Fixed X) implies the section is listing issues in
_previous_ releases that are fixed in this one.
I'd like to send a PR to clarify this, but which interpretation is correct:
"Known Issues," or "Fixed Issues"? It looks like we've used both
interchangeably for the last few releases.
Thanks,
Brian
[1] https://github.com/apache/beam/blame/master/CHANGES.md
Re: Release Notes: "Known Issues" or "Fixed Issues"?
Posted by Udi Meiri <eh...@google.com>.
I interpret it as bugs discovered in this release that have not been fixed.
These may be: a backwards compatibility breakage, a regression, an
in-progress feature that doesn't work yet.
The word "fixed" may have been copied from other sections.
On Mon, Sep 13, 2021 at 4:01 PM Brian Hulette <bh...@google.com> wrote:
> Our release notes template [1] contains the following section:
>
>
> ## Known Issues
> * Fixed X (Java/Python) ([BEAM-X](
> https://issues.apache.org/jira/browse/BEAM-X)).
>
>
> I find this hard to interpret:
> - The title (Known Issues) implies the section is meant to enumerate
> issues that we discover in a release after it is too late to fix them.
> - The bullet text (Fixed X) implies the section is listing issues in
> _previous_ releases that are fixed in this one.
>
> I'd like to send a PR to clarify this, but which interpretation is
> correct: "Known Issues," or "Fixed Issues"? It looks like we've used both
> interchangeably for the last few releases.
>
> Thanks,
> Brian
>
> [1] https://github.com/apache/beam/blame/master/CHANGES.md
>
Re: Release Notes: "Known Issues" or "Fixed Issues"?
Posted by Brian Hulette <bh...@google.com>.
Ah thanks everyone for the input, and thanks Ahmet for digging up the
original template. I guess it was accidentally mangled at some point. I've
proposed [1] to fix.
[1] https://github.com/apache/beam/pull/15516
On Tue, Sep 14, 2021 at 3:39 PM Ahmet Altay <al...@google.com> wrote:
> Originally we had the following text [1], and it seems like this is what
> we are proposing again. It is possible that changes.md changed over time in
> an unintentional way and it would be good restore the template to its
> original state.
>
> ### Bugfixes
>
> * Fixed X (Java/Python) ([BEAM-X](
> https://issues.apache.org/jira/browse/BEAM-X)).
>
> ### Known Issues
>
> * ([BEAM-X](https://issues.apache.org/jira/browse/BEAM-X)).
>
> [1]
> https://github.com/apache/beam/pull/10743/files#diff-d975bf659606195d2165918f93e1cf680ef68ea3c9cab994f033705fea8238b2
>
> On Tue, Sep 14, 2021 at 3:11 PM Daniel Oliveira <da...@google.com>
> wrote:
>
>> I'm with Udi's interpretation, that "Known Issues" is for issues we
>> haven't fixed in the release. And I support Kyle's idea of having a
>> separate section for bugfixes. Rereading the template now, I'm a bit
>> surprised there isn't already a bugfix section. I'm used to most changelogs
>> including one.
>>
>> On Mon, Sep 13, 2021 at 4:11 PM Kyle Weaver <kc...@google.com> wrote:
>>
>>> Having a section for each seems useful as long as they're unambiguous.
>>> Maybe "known issues with this release" vs. "issues fixed in this release."
>>>
>>> On Mon, Sep 13, 2021 at 4:01 PM Brian Hulette <bh...@google.com>
>>> wrote:
>>>
>>>> Our release notes template [1] contains the following section:
>>>>
>>>>
>>>> ## Known Issues
>>>> * Fixed X (Java/Python) ([BEAM-X](
>>>> https://issues.apache.org/jira/browse/BEAM-X)).
>>>>
>>>>
>>>> I find this hard to interpret:
>>>> - The title (Known Issues) implies the section is meant to enumerate
>>>> issues that we discover in a release after it is too late to fix them.
>>>> - The bullet text (Fixed X) implies the section is listing issues in
>>>> _previous_ releases that are fixed in this one.
>>>>
>>>> I'd like to send a PR to clarify this, but which interpretation is
>>>> correct: "Known Issues," or "Fixed Issues"? It looks like we've used both
>>>> interchangeably for the last few releases.
>>>>
>>>> Thanks,
>>>> Brian
>>>>
>>>> [1] https://github.com/apache/beam/blame/master/CHANGES.md
>>>>
>>>
Re: Release Notes: "Known Issues" or "Fixed Issues"?
Posted by Ahmet Altay <al...@google.com>.
Originally we had the following text [1], and it seems like this is what we
are proposing again. It is possible that changes.md changed over time in an
unintentional way and it would be good restore the template to its original
state.
### Bugfixes
* Fixed X (Java/Python) ([BEAM-X](
https://issues.apache.org/jira/browse/BEAM-X)).
### Known Issues
* ([BEAM-X](https://issues.apache.org/jira/browse/BEAM-X)).
[1]
https://github.com/apache/beam/pull/10743/files#diff-d975bf659606195d2165918f93e1cf680ef68ea3c9cab994f033705fea8238b2
On Tue, Sep 14, 2021 at 3:11 PM Daniel Oliveira <da...@google.com>
wrote:
> I'm with Udi's interpretation, that "Known Issues" is for issues we
> haven't fixed in the release. And I support Kyle's idea of having a
> separate section for bugfixes. Rereading the template now, I'm a bit
> surprised there isn't already a bugfix section. I'm used to most changelogs
> including one.
>
> On Mon, Sep 13, 2021 at 4:11 PM Kyle Weaver <kc...@google.com> wrote:
>
>> Having a section for each seems useful as long as they're unambiguous.
>> Maybe "known issues with this release" vs. "issues fixed in this release."
>>
>> On Mon, Sep 13, 2021 at 4:01 PM Brian Hulette <bh...@google.com>
>> wrote:
>>
>>> Our release notes template [1] contains the following section:
>>>
>>>
>>> ## Known Issues
>>> * Fixed X (Java/Python) ([BEAM-X](
>>> https://issues.apache.org/jira/browse/BEAM-X)).
>>>
>>>
>>> I find this hard to interpret:
>>> - The title (Known Issues) implies the section is meant to enumerate
>>> issues that we discover in a release after it is too late to fix them.
>>> - The bullet text (Fixed X) implies the section is listing issues in
>>> _previous_ releases that are fixed in this one.
>>>
>>> I'd like to send a PR to clarify this, but which interpretation is
>>> correct: "Known Issues," or "Fixed Issues"? It looks like we've used both
>>> interchangeably for the last few releases.
>>>
>>> Thanks,
>>> Brian
>>>
>>> [1] https://github.com/apache/beam/blame/master/CHANGES.md
>>>
>>
Re: Release Notes: "Known Issues" or "Fixed Issues"?
Posted by Daniel Oliveira <da...@google.com>.
I'm with Udi's interpretation, that "Known Issues" is for issues we haven't
fixed in the release. And I support Kyle's idea of having a separate
section for bugfixes. Rereading the template now, I'm a bit surprised there
isn't already a bugfix section. I'm used to most changelogs including one.
On Mon, Sep 13, 2021 at 4:11 PM Kyle Weaver <kc...@google.com> wrote:
> Having a section for each seems useful as long as they're unambiguous.
> Maybe "known issues with this release" vs. "issues fixed in this release."
>
> On Mon, Sep 13, 2021 at 4:01 PM Brian Hulette <bh...@google.com> wrote:
>
>> Our release notes template [1] contains the following section:
>>
>>
>> ## Known Issues
>> * Fixed X (Java/Python) ([BEAM-X](
>> https://issues.apache.org/jira/browse/BEAM-X)).
>>
>>
>> I find this hard to interpret:
>> - The title (Known Issues) implies the section is meant to enumerate
>> issues that we discover in a release after it is too late to fix them.
>> - The bullet text (Fixed X) implies the section is listing issues in
>> _previous_ releases that are fixed in this one.
>>
>> I'd like to send a PR to clarify this, but which interpretation is
>> correct: "Known Issues," or "Fixed Issues"? It looks like we've used both
>> interchangeably for the last few releases.
>>
>> Thanks,
>> Brian
>>
>> [1] https://github.com/apache/beam/blame/master/CHANGES.md
>>
>
Re: Release Notes: "Known Issues" or "Fixed Issues"?
Posted by Kyle Weaver <kc...@google.com>.
Having a section for each seems useful as long as they're unambiguous.
Maybe "known issues with this release" vs. "issues fixed in this release."
On Mon, Sep 13, 2021 at 4:01 PM Brian Hulette <bh...@google.com> wrote:
> Our release notes template [1] contains the following section:
>
>
> ## Known Issues
> * Fixed X (Java/Python) ([BEAM-X](
> https://issues.apache.org/jira/browse/BEAM-X)).
>
>
> I find this hard to interpret:
> - The title (Known Issues) implies the section is meant to enumerate
> issues that we discover in a release after it is too late to fix them.
> - The bullet text (Fixed X) implies the section is listing issues in
> _previous_ releases that are fixed in this one.
>
> I'd like to send a PR to clarify this, but which interpretation is
> correct: "Known Issues," or "Fixed Issues"? It looks like we've used both
> interchangeably for the last few releases.
>
> Thanks,
> Brian
>
> [1] https://github.com/apache/beam/blame/master/CHANGES.md
>