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

[Ben Finney]

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

> > 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.
> 
> following your logic, you can check the thread to know who I'm
> referring to.

I don't know what you refer to here, but I don't follow the logic. I'm
requesting you follow a common convention for courtesy and clarity in
email discussions, unrelated to the discussion in this thread. I hope
you will do so, in the interest of all readers of your messages.

If you've got some other point here, perhaps you'd like to discuss it
with me in private email.

> > I refer to the Developer's Reference "Best Practices" chapter
> 
> and in §1 that document states
> 
>   Furthermore, this document is not an expression of formal policy
>   . It contains documentation for the Debian system and generally
>   agreed-upon best practices. Thus, it is not what is called a
>   ``normative'' document.

Yes, which is why I reference it for best practices for Debian
packages.

> What I'm referring to is Debian Policy, "The Document" about what
> must be in packages:
> 
> 4.4. Debian changelog: `debian/changelog'
> -----------------------------------------
> 
>      Changes in the Debian version of the package should be briefly
>      explained in the Debian changelog file `debian/changelog'.[1] This
>      includes modifications made in the Debian package compared to the
>      upstream one as well as other changes and updates to the package.  [2]
> (...)
> [2]  Although there is nothing stopping an author who is also the Debian
>      maintainer from using this changelog for all their changes, it will
>      have to be renamed if the Debian and upstream maintainers become
>      different people.  In such a case, however, it might be better to
>      maintain the package as a non-native package.

All this is silent on whether "internal" changes should or should not
be in the 'debian/changelog'.

> I'd like to highlight "as well as other changes and updates to the
> package", so I'm following what Policy says, and that's the way to go,
> no excuses.

I don't know whether English is your first language, but to this
native English speaker, the phrase "includes modifications [...]
compared to the upstream one as well as other changes and updates"
certainly does not imply "includes *all possible* modifications and
changes and updates". Rather, it implies "includes modifications such
as these", without implying all possible members of the class must be
included.

So, the Policy document doesn't require what you seem to be saying it
requires. It doesn't forbid it, either: it isn't prescriptive either
way.

That's why I referred to the "best practices" Dev Ref chapter, which,
while non-normative, purports to represent widely agreed-upon best
practices in the Debian community.

> >> *I* will continue with what I think it's the right way [...]
> >
> > 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 can't see how can we come to an agreement, when someone with a
> "little" more experience says something about the de-facto usage of
> debian/changelog and it's not trusted.

I would very much like for the reportbug-maint team to come to an
agreement about this. It seems, though, that the disagreement is
between what you prefer and the current documented "best practices" of
the Debian project.

One or the other should change. I've cast my vote on which, but either
(or both) is possible :-)

> Please, contact real person, real DDs, and ask them about it.

Perhaps that's the next step, then: to discuss this on debian-devel to
see current opinion of this provision in the Developer's Reference.

I'll assume anyone who wants to follow this discussion can follow it
on debian-devel; I won't Cc this list.

-- 
 \              "In the long run, the utility of all non-Free software |
  `\      approaches zero. All non-Free software is a dead end." —Mark |
_o__)                                                    Pilgrim, 2006 |
Ben Finney