[vtk-developers] Thoughts on changelog maintenance?

[Jon Haitz Legarreta]

I may be missing some point, so I'd like to apologize if that turns
out to be the case.

But what's the advantage of keeping a changelog per MR/topic if the
subject of the topic is meaningful or self-contained?

That being said, having a CHANGELOG.md file, whatever its generation
process is, seems fair to me.

> I support anything that move us further away from the
> centralized/semi-manual way we make releases now

Dave, the "centralized/semi-manual way" you mention refers only to the
changelog documentation generation or the whole release process (and
thus making the discussion have a wider span)?

Looks like there will always be a manual consolidation effort, which
may be burdensome, right? I ignore about other mechanisms other C++
libraries or Python packages, for example, may have. Although, the
Python scope is different, their "What's New" document is quite dense,
and their changelog seems to be a collection of tickets from their
issue tracker.

> Even issues aren't 1:1 for "what's important" in a release. It's better,
> but still not much better than using the git log (IMO).

As David and Ben said, I'm afraid that having an issue to topic/MR
ratio of 1:1 is not realistic right now. But if we think we should
enforce that, I think we could learn living with it.

May be that would also require opening issues that have more to do
with tasks, milestones, or the toolkit's roadmap.

If we are happy with the current mechanism to summarize our changes,
I'd may be propose providing a set of recommendations, including the
response time, (through an .md file in the documentation), so that the
answers we deliver can be consistent across developers/releases.

May be some mechanism can be developed to ping automatically
contributors that have MRs for a given release, and submit the
summaries to Gitlab? I ignore whether currently a script exists to
gather all merged MRs for a release; then all contributors GitLab user
could be gathered and may be an issue in GitLab could be opened with a
pre-defined message asking all contributors to provide a summary in an
.md file/format?

I guess that would save time to maintainers, avoiding sending all
individual mails requesting a summary, and collecting them.

Finally, may be sectioning in the changelog (manual consolidation step
or in the simple ticket gathering) is also relevant: using Elvis'
feed, should it have a pre-defined sectioning (like enhancements per
module, documentation improvements, language/compiler/platform
support/compatibility changes, new tests, examples, etc.)?


JON HAITZ

--


On 7 November 2017 at 21:55, Ben Boeckel <ben.boeckel at kitware.com> wrote:
>
> On Tue, Nov 07, 2017 at 12:54:02 -0700, David Gobbi wrote:
> > In a perfect world, the changelog would be generated automatically from all
> > of the issues that were closed between releases.  That would require much
> > more frequent use of the issue tracker (which would be a good thing).
> > Issues and MRs would continue to be tied together via gitlab references.
>
> Even issues aren't 1:1 for "what's important" in a release. It's better,
> but still not much better than using the git log (IMO).
>
> > If someone wanted to see the latest changelog for master, they would just
> > go to gitlab's list of closed issues.  The changelog put into the source
> > upon release would just be an md file that was a copy of the same.
>
> But asking "what's different between 8.1 and 9.0?" is hard because you
> have to know dates to filter on (and I'm not sure how good Gitlab's
> filters are there).
>
> > Overall, though, I'm not sure if a new changelog mechanism is even needed.
> > The current workflow (summarizing our changes at release time) already
> > seems pleasantly lightweight.
>
> The issue is that during releases, some people can take weeks to reply.
> How long do we wait? If we're going to end up going through ourselves
> anyways, why not try and get it upfront? Plus, we tend to miss any fixes
> after rc1 since we don't send emails again.
>
> --Ben
> _______________________________________________
> Powered by www.kitware.com
>
> Visit other Kitware open-source projects at http://www.kitware.com/opensource/opensource.html
>
> Search the list archives at: http://markmail.org/search/?q=vtk-developers
>
> Follow this link to subscribe/unsubscribe:
> http://public.kitware.com/mailman/listinfo/vtk-developers
>