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

[Chris Lawrence]

On Fri, Jun 13, 2008 at 2:57 AM, Ben Finney <ben+debian at benfinney.id.au> wrote:
> "Sandro Tosi" <matrixhasu at gmail.com> writes:
>> 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.

Without wading too far into the weeds here, I think we probably should
think about this from the perspective of "what is the purpose of
debian/changelog?"  Since reportbug is a native package, this
changelog conveys all of the changes in the package, absent some more
detailed log (and I'm not sure the subversion log is going to be all
that visible to people using the package).

People generally seem to look at debian/changelog a lot to figure out
"what broke my reportbug?"  As such we probably should document things
that might break people's reportbug there.  I'm not sure it needs to
be at the detail of the commit log, but I'm not sure "only
user-visible changes" is a useful boundary either.

My gut feeling is that non-user-visible changes should be mentioned,
but there's no need to go into any particular detail unless it fixes a
bug report, and there's no need to list each commit separately if
there are multiple commits to the same end; something like "improved
speed of dependency resolution" or "using SOAP interface instead of
HTML scraping to access BTS" would suffice.


Chris