Release note issue filtering

[Stig Rohde Døssing <st...@gmail.com>]

I took a look at the release notes generated by JIRA and the
dev-tools/release_notes.py script for 1.2.0, and noticed that it includes a
lot of fixes that are also fixed in earlier versions. JIRA seems to only
care about whether or not the listed fix version includes 1.2.0,
disregarding whether the fix was released in an earlier version. I think
this can cause release notes for a version to be very large, e.g. 2.0.0
will include lots of fixes that were already applied in 1.x.

With the previous CHANGELOG.md we sometimes listed fixes applied to
multiple versions only in the earliest version containing that fix. We can
do something similar with the JIRA script, by removing any issue that is
resolved in an earlier released version. We'd need to mark releases as
released to get this to work, but that seems doable.

The downside to this type of filtering is that it means that some issues
might end up hidden in release notes some users won't read. For example if
we currently have 1.0.2 and 1.1.0 released, and we fix an issue in both
branches, only the 1.0.3 release notes will show the bugfix. 1.1.1 doesn't
show it because it was fixed in an earlier released version. Users already
on 1.1.0 might not read the release notes for 1.0.3, because they're not
going to downgrade, so they'll miss the bugfix. I haven't found a good
heuristic for when this kind of issue should be in both release notes.

Any opinions on whether we should filter the issues, or suggestions for
what the rules for filtering should be?

Re: Release note issue filtering

[Stig Rohde Døssing <st...@gmail.com>]

Took a quick look at a few other projects. Kafka doesn't currently do
maintenance releases, so they don't have this problem. Zookeeper links to
the JIRA search for their release notes, which means no filtering. Spark
provides a summary of big changes with no duplicates, and a full release
notes log that is unfiltered. I'm not sure if the summary is written
manually (example page
https://spark.apache.org/releases/spark-release-2-1-0.html).

2017-08-27 1:22 GMT+02:00 Jungtaek Lim <ka...@gmail.com>:

> I'm aware of this issue and I don't have other idea than what you
> suggested. I'm OK to mark released version as 'released' and only
> enumerating unreleased issues. It looks simplest and IMHO still less
> error-prone than manually editing CHANGELOG.
>
> I guess other projects would have similar issue as well so if someone
> working to other projects as well sheds a light, that should be great.
> Maintaining major / minor / bugfix branches together would be not trivial
> case though.
>
> - Jungtaek Lim (HeartSaVioR)
>
> 2017년 8월 27일 (일) 오전 6:36, Stig Rohde Døssing <st...@gmail.com>님이
> 작성:
>
> > I took a look at the release notes generated by JIRA and the
> > dev-tools/release_notes.py script for 1.2.0, and noticed that it
> includes a
> > lot of fixes that are also fixed in earlier versions. JIRA seems to only
> > care about whether or not the listed fix version includes 1.2.0,
> > disregarding whether the fix was released in an earlier version. I think
> > this can cause release notes for a version to be very large, e.g. 2.0.0
> > will include lots of fixes that were already applied in 1.x.
> >
> > With the previous CHANGELOG.md we sometimes listed fixes applied to
> > multiple versions only in the earliest version containing that fix. We
> can
> > do something similar with the JIRA script, by removing any issue that is
> > resolved in an earlier released version. We'd need to mark releases as
> > released to get this to work, but that seems doable.
> >
> > The downside to this type of filtering is that it means that some issues
> > might end up hidden in release notes some users won't read. For example
> if
> > we currently have 1.0.2 and 1.1.0 released, and we fix an issue in both
> > branches, only the 1.0.3 release notes will show the bugfix. 1.1.1
> doesn't
> > show it because it was fixed in an earlier released version. Users
> already
> > on 1.1.0 might not read the release notes for 1.0.3, because they're not
> > going to downgrade, so they'll miss the bugfix. I haven't found a good
> > heuristic for when this kind of issue should be in both release notes.
> >
> > Any opinions on whether we should filter the issues, or suggestions for
> > what the rules for filtering should be?
> >
>

Re: Release note issue filtering

[Jungtaek Lim <ka...@gmail.com>]

I'm aware of this issue and I don't have other idea than what you
suggested. I'm OK to mark released version as 'released' and only
enumerating unreleased issues. It looks simplest and IMHO still less
error-prone than manually editing CHANGELOG.

I guess other projects would have similar issue as well so if someone
working to other projects as well sheds a light, that should be great.
Maintaining major / minor / bugfix branches together would be not trivial
case though.

- Jungtaek Lim (HeartSaVioR)

2017년 8월 27일 (일) 오전 6:36, Stig Rohde Døssing <st...@gmail.com>님이 작성:

> I took a look at the release notes generated by JIRA and the
> dev-tools/release_notes.py script for 1.2.0, and noticed that it includes a
> lot of fixes that are also fixed in earlier versions. JIRA seems to only
> care about whether or not the listed fix version includes 1.2.0,
> disregarding whether the fix was released in an earlier version. I think
> this can cause release notes for a version to be very large, e.g. 2.0.0
> will include lots of fixes that were already applied in 1.x.
>
> With the previous CHANGELOG.md we sometimes listed fixes applied to
> multiple versions only in the earliest version containing that fix. We can
> do something similar with the JIRA script, by removing any issue that is
> resolved in an earlier released version. We'd need to mark releases as
> released to get this to work, but that seems doable.
>
> The downside to this type of filtering is that it means that some issues
> might end up hidden in release notes some users won't read. For example if
> we currently have 1.0.2 and 1.1.0 released, and we fix an issue in both
> branches, only the 1.0.3 release notes will show the bugfix. 1.1.1 doesn't
> show it because it was fixed in an earlier released version. Users already
> on 1.1.0 might not read the release notes for 1.0.3, because they're not
> going to downgrade, so they'll miss the bugfix. I haven't found a good
> heuristic for when this kind of issue should be in both release notes.
>
> Any opinions on whether we should filter the issues, or suggestions for
> what the rules for filtering should be?
>