[Reportbug-maint] reportbug project: Changelog entries versus VCS commit messages

[Ben Finney]

Sandro, please preserve attribution lines when you include quoted
material. Omitting them means we don't know who wrote the material
quoted at each level.

"Sandro Tosi" <matrixhasu at gmail.com> writes:

> >> However, documenting minor changes may mean that the larger and
> >> more important changes that we want people to know would really
> >> be 'lost in the crowd', so to speak. I would say, use your good
> >> judgement :)
> >
> > This is my concern too. If the package changelog documents
> > purely-internal changes as well as user-visible changes, it
> > becomes far too verbose for users.
> 
> So, what should I write in changelog if I did only internal changes?

I refer to the Developer's Reference "Best Practices" chapter
<URL:http://www.debian.org/doc/developers-reference/ch-best-pkging-practices.en.html#s-bpp-debian-changelog>,
which says:

    The changelog entry for a package revision documents changes in
    that revision, and only them. Concentrate on describing
    significant and user-visible changes that were made since the last
    version.

    [...]
    There's no need to elaborate the trivial and obvious changes.

    [...]
    Use common English so that the majority of readers can comprehend
    it. Avoid abbreviations, "tech-speak" and jargon when explaining
    changes that close bugs, especially for bugs filed by users that
    did not strike you as particularly technically savvy.

This puts a strong focus on keeping the changelog's *primary* audience
as the users of the package, keeping the file usable to them by not
including loads of development-internal information.

If the changes were purely internal, it appears you have nothing to
tell the users, and thus (by the above best practice) nothing to put
in the changelog.

If there was some user-visible impact of those internal changes,
that's what should be described in the changelog.

> *I* will continue with what I think it's the right way to write
> debian/changelog (supported by many DDs and moreover by policy), of
> course you are free to do what's best for you to get the work done.

This doesn't seem to be a good approach to the changelog, which is an
important interface for our package. We should come to an agreement
about what should go into the changelog, rather than each going our
own way.

-- 
 \       "I was the kid next door's imaginary friend."  -- Emo Philips |
  `\                                                                   |
_o__)                                                                  |
Ben Finney