Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Sean Whitton]

control: tag -1 +pending

Hello,

On Tue, Aug 22 2017, Mattia Rizzolo wrote:

> LGTM, seconded.

Applied, thanks.

> That said, I'd expect the upgrade-checklist to say that this change is
> about clarifying that debian/copyright must exist (where before it was
> "fine" not existing).

Not sure what you're asking.  Let me know if what I just pushed could be
better.

-- 
Sean Whitton


signature.asc
Description: PGP signature

Processed: Re: Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Debian Bug Tracking System]

Processing control commands:

> tag -1 +pending
Bug #683222 [debian-policy] say explicitly that debian/changelog is required in 
source packages
Added tag(s) pending.

-- 
683222: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=683222
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems

Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Mattia Rizzolo]

On Mon, Aug 21, 2017 at 05:22:12PM -0700, Sean Whitton wrote:
> Commenting on Charles' patch, I think that it would be clearer to have
> the 'should' and 'must' requirements in separate sentences.

Good idea.

> diff --git a/policy/ch-source.rst b/policy/ch-source.rst
> index f706a13..89b355a 100644
> --- a/policy/ch-source.rst
> +++ b/policy/ch-source.rst
> @@ -99,10 +99,11 @@ later reconfigure the package without losing the changes 
> you made.
>  Debian changelog: ``debian/changelog``
>  --
>  
> -Changes in the Debian version of the package should be briefly explained
> -in the Debian changelog file ``debian/changelog``.  [#]_ This includes
> -modifications made in the Debian package compared to the upstream one as
> -well as other changes and updates to the package.  [#]_
> +Every source package must include the Debian changelog file,
> +``debian/changelog``.  Changes in the Debian version of the package
> +should be briefly explained in this file.  [#]_ This includes
> +modifications made in the Debian package compared to the upstream one
> +as well as other changes and updates to the package.  [#]_
>  
>  The format of the ``debian/changelog`` allows the package building tools
>  to discover which version of the package is being built and find out

LGTM, seconded.


That said, I'd expect the upgrade-checklist to say that this change is
about clarifying that debian/copyright must exist (where before it was
"fine" not existing).

-- 
regards,
Mattia Rizzolo

GPG Key: 66AE 2B4A FCCF 3F52 DA18  4D18 4B04 3FCD B944 4540  .''`.
more about me:  https://mapreri.org : :'  :
Launchpad user: https://launchpad.net/~mapreri  `. `'`
Debian QA page: https://qa.debian.org/developer.php?login=mattia  `-


signature.asc
Description: PGP signature

Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Russ Allbery]

Sean Whitton  writes:

> Thus I am seeking seconds for the following patch:

> diff --git a/policy/ch-source.rst b/policy/ch-source.rst
> index f706a13..89b355a 100644
> --- a/policy/ch-source.rst
> +++ b/policy/ch-source.rst
> @@ -99,10 +99,11 @@ later reconfigure the package without losing the changes 
> you made.
>  Debian changelog: ``debian/changelog``
>  --
>  
> -Changes in the Debian version of the package should be briefly explained
> -in the Debian changelog file ``debian/changelog``.  [#]_ This includes
> -modifications made in the Debian package compared to the upstream one as
> -well as other changes and updates to the package.  [#]_
> +Every source package must include the Debian changelog file,
> +``debian/changelog``.  Changes in the Debian version of the package
> +should be briefly explained in this file.  [#]_ This includes
> +modifications made in the Debian package compared to the upstream one
> +as well as other changes and updates to the package.  [#]_
>  
>  The format of the ``debian/changelog`` allows the package building tools
>  to discover which version of the package is being built and find out

Looks good to me.  Seconded.

-- 
Russ Allbery (r...@debian.org)   

Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Jonathan Nieder]

Sean Whitton wrote:
> On Wed, Aug 01, 2012 at 08:07:01AM +0900, Charles Plessy wrote:

>> Otherwise, how about something along these lines: [...]
>
> Commenting on Charles' patch, I think that it would be clearer to have
> the 'should' and 'must' requirements in separate sentences.
>
> Thus I am seeking seconds for the following patch:
>
> diff --git a/policy/ch-source.rst b/policy/ch-source.rst
> index f706a13..89b355a 100644
> --- a/policy/ch-source.rst
> +++ b/policy/ch-source.rst
> @@ -99,10 +99,11 @@ later reconfigure the package without losing the changes 
> you made.
>  Debian changelog: ``debian/changelog``
>  --
>  
> -Changes in the Debian version of the package should be briefly explained
> -in the Debian changelog file ``debian/changelog``.  [#]_ This includes
> -modifications made in the Debian package compared to the upstream one as
> -well as other changes and updates to the package.  [#]_
> +Every source package must include the Debian changelog file,
> +``debian/changelog``.  Changes in the Debian version of the package
> +should be briefly explained in this file.  [#]_ This includes
> +modifications made in the Debian package compared to the upstream one
> +as well as other changes and updates to the package.  [#]_
> 
>  The format of the ``debian/changelog`` allows the package building tools
>  to discover which version of the package is being built and find out

Seconded.  Thanks for tying up this loose end.

Sincerely,
Jonathan

Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Sean Whitton]

control: tag -1 +patch

On Wed, Aug 01, 2012 at 08:07:01AM +0900, Charles Plessy wrote:
> Otherwise, how about something along these lines: [...]

Commenting on Charles' patch, I think that it would be clearer to have
the 'should' and 'must' requirements in separate sentences.

Thus I am seeking seconds for the following patch:

diff --git a/policy/ch-source.rst b/policy/ch-source.rst
index f706a13..89b355a 100644
--- a/policy/ch-source.rst
+++ b/policy/ch-source.rst
@@ -99,10 +99,11 @@ later reconfigure the package without losing the changes 
you made.
 Debian changelog: ``debian/changelog``
 --
 
-Changes in the Debian version of the package should be briefly explained
-in the Debian changelog file ``debian/changelog``.  [#]_ This includes
-modifications made in the Debian package compared to the upstream one as
-well as other changes and updates to the package.  [#]_
+Every source package must include the Debian changelog file,
+``debian/changelog``.  Changes in the Debian version of the package
+should be briefly explained in this file.  [#]_ This includes
+modifications made in the Debian package compared to the upstream one
+as well as other changes and updates to the package.  [#]_
 
 The format of the ``debian/changelog`` allows the package building tools
 to discover which version of the package is being built and find out

-- 
Sean Whitton


signature.asc
Description: PGP signature

Processed: Re: Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Debian Bug Tracking System]

Processing control commands:

> tag -1 +patch
Bug #683222 [debian-policy] say explicitly that debian/changelog is required in 
source packages
Added tag(s) patch.

-- 
683222: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=683222
Debian Bug Tracking System
Contact ow...@bugs.debian.org with problems

Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Charles Plessy]

Le Sun, Jul 29, 2012 at 05:16:16PM -0700, Russ Allbery a écrit :
 
 I think you've been confused into thinking that Policy 4.4 is about the
 presence of the file rather than its usage.  Policy doesn't say anything
 about the existence of the file in source packages right now.  This
 strikes me as obvious, which is probably why no one has bothered, but we
 can add a sentence somewhere saying that the file has to exist.

Hi all,

just to be sure, I went to the Lintian lab, and I did not see any source
package that did not contain a debian/changelog file. Therefore, we can
explicitely require its presence.

How about documenting changelogs in the same way as we document copyright
files:

 - In chapter 4, describing source packages, require their presence in
   debian/changelog.

 - In chapter 12, about documentation, provide the information about the format
   and the contents.

This is quite an extensive modification (it transfer all the description of the 
format
to chapter 12, but could be part of the restructuring
work for Policy 4.0.

Otherwise, how about something along these lines:

--- a/policy.sgml
+++ b/policy.sgml
@@ -1591,12 +1591,12 @@
   /sect
 
   sect id=dpkgchangelog
-   headingDebian changelog: filedebian/changelog/file/heading
+   headingDebian changelog: filedebian/changelog/file 
(required)/heading
 
p
- Changes in the Debian version of the package should be
+ Changes in the Debian Source package should be
  briefly explained in the Debian changelog file
- filedebian/changelog/file.footnote
+ filedebian/changelog/file, which is required.footnote
 p
   Mistakes in changelogs are usually best rectified by
   making a new changelog entry rather than rewriting


Cheers,

-- 
Charles Plessy
Tsurumi, Kanagawa, Japan


--
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/20120731230700.ge16...@falafel.plessy.net

Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Arno Töll]

Hi,

On 30.07.2012 02:16, Russ Allbery wrote:
 Correct.  It's not an RC bug to not describe a change in the Debian
 version of the package, just a normal bug.

Yes. I think the confusion arises from the ambiguity. I think the
should refers to the optional principle to describe changes, not to
the existence of such a file. That's also what you are saying below. It
can be read and misunderstood the way I did, however.

 This strikes me as obvious, which is probably why no one has
 bothered, but we can add a sentence somewhere saying that the file
 has to exist.

Please do. Alternatively it may work to rephrase the sentence in 4.4 and
make more explicit it refers to the contents of that file, not the
existence of the file itself.

 Must for the existing language is definitely wrong, since it would be
 saying that it's an RC bug to miss describing a change to the package.  I
 don't think we want to go there.

Indeed. That wasn't my intention either.


-- 
with kind regards,
Arno Töll
IRC: daemonkeeper on Freenode/OFTC
GnuPG Key-ID: 0x9D80F36D



signature.asc
Description: OpenPGP digital signature

Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Arno Töll]

Package: debian-policy
Severity: normal

Policy section 4.4 states (emphasize mine):

  Changes in the Debian version of the package _should_ be briefly explained in 
the
  Debian changelog file debian/changelog.[15] [..]

This implies, use of debian/changelog is optional with respect to the normative
meaning of should in the policy manual. However, reading section 12.7 this is 
not
true:

  Packages that are not Debian-native must contain a compressed copy of the
  debian/changelog file from the Debian source tree in /usr/share/doc/package 
with
  the name changelog.Debian.gz.

I realize, section 4.4 refers to the source package, whereas 12.7 refers to 
binary
packages. Having that said, that's hardly a difference for most packages anyway
and even section 12.7 refers to the source package as origin for that file 
(must
contain a compressed copy of the debian/changelog file from the Debian source
tree).

Please add a sentence for clarification to section 4.4, or replace the should 
in
4.4 by must for consistency.

-- System Information:
Debian Release: wheezy/sid
  APT prefers unstable
  APT policy: (500, 'unstable')
Architecture: amd64 (x86_64)

Kernel: Linux 3.3.0-trunk-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash


-- 
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: 
http://lists.debian.org/20120729214815.5324.23718.report...@snowball.fritz.box

Bug#683222: debian-policy: Policy section 4.4 is imprecise with respect to section 12.7

[Russ Allbery]

Arno Töll a...@debian.org writes:

 Policy section 4.4 states (emphasize mine):

   Changes in the Debian version of the package _should_ be briefly
   explained in the Debian changelog file debian/changelog.[15] [..]

 This implies, use of debian/changelog is optional with respect to the
 normative meaning of should in the policy manual.

Correct.  It's not an RC bug to not describe a change in the Debian
version of the package, just a normal bug.

 However, reading section 12.7 this is not true:

   Packages that are not Debian-native must contain a compressed copy of
   the debian/changelog file from the Debian source tree in
   /usr/share/doc/package with the name changelog.Debian.gz.

This is about something completely different, namely the presence of the
changelog file.

I think you've been confused into thinking that Policy 4.4 is about the
presence of the file rather than its usage.  Policy doesn't say anything
about the existence of the file in source packages right now.  This
strikes me as obvious, which is probably why no one has bothered, but we
can add a sentence somewhere saying that the file has to exist.

 Please add a sentence for clarification to section 4.4, or replace the
 should in 4.4 by must for consistency.

Must for the existing language is definitely wrong, since it would be
saying that it's an RC bug to miss describing a change to the package.  I
don't think we want to go there.

-- 
Russ Allbery (r...@debian.org)   http://www.eyrie.org/~eagle/


--
To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org
with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org
Archive: http://lists.debian.org/87mx2ip0hb@windlord.stanford.edu