[policy] 01/01: Clarify usage of debian/changelog file

[Andreas Tille]

This is an automated email from the git hooks/post-receive script.

tille pushed a commit to branch master
in repository policy.

commit f68caa5d65096fd7f8fba339784c77a0b34f60a1
Author: Pablo de Oliveira <pablo at sifflez.org>
Date:   Fri Oct 25 14:34:07 2013 +0200

    Clarify usage of debian/changelog file
    
    * As suggested in http://lists.debian.org/debian-mentors/2013/10/msg00321.html
---
 debian-science-policy.xml |   47 ++++++++++++++++++++++++++++++---------------
 1 file changed, 31 insertions(+), 16 deletions(-)

diff --git a/debian-science-policy.xml b/debian-science-policy.xml
index ee9f1d0..3a02332 100644
--- a/debian-science-policy.xml
+++ b/debian-science-policy.xml
@@ -27,22 +27,23 @@
       CDBS is no longer recommended. Debian source package formats 3.0 is now mandatory.</revremark>
     </revision>
     <revision>
-      <revnumber>1.1</revnumber>
-      <date>2013-09-11</date>
-      <authorinitials>PO</authorinitials>
-      <revremark>
-        * Fix the path to VCS-*
-      * Point the DEP5 link to the correct place
-      * Update the git url
-* Clarify that /git/ is mounted read-only on alioth.debian.org and one should log into git.debian.org instead.
-
-* Give the reportbug syntax to put debian-maintainers in CC when filling a new ITP bug
-
-* Fix example to activate post-update hook in git
-* Add a link to gpb in section Package Repositories
-* Fix FIXME requesting internal links
-</revremark>
+        <revnumber>1.1</revnumber>
+        <date>2013-09-11</date>
+        <authorinitials>PO</authorinitials>
+        <revremark>
+            Fix the path to VCS-*; Point the DEP5 link to the correct place; Update the git url; Clarify that /git/ is mounted read-only on alioth.debian.org and one should log into git.debian.org instead.; 
+            Give the reportbug syntax to put debian-maintainers in CC when filling a new ITP bug; Fix example to activate post-update hook in git; Add a link to gpb in section Package Repositories; Fix FIXME requesting internal links
+        </revremark>
+    </revision>
+    <revision>
+        <revnumber>1.2</revnumber>
+        <date>2013-10-25</date>
+        <authorinitials>PO</authorinitials>
+        <revremark>
+            Clarify rules regarding debian/changelog
+        </revremark>
     </revision>
+
   </revhistory>
 </bookinfo>
 <preface>
@@ -71,6 +72,20 @@
     <title>Debian Control Files</title>
     <para>The following sections describe the changes to the control files stored in the source package's <filename>debian/</filename> directory.</para>
     <sect2>
+      <title><filename>debian/changelog</filename></title>
+      <para>Changes in the Debian version of the package should be briefly explained in the Debian changelog file.
+            The <filename>debian/changelog</filename> file consists in a series of entries detailing the changes. The format of the entries is described
+            in the <ulink url="http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog">Debian Policy</ulink>.
+      </para>
+      <para>Not yet uploaded packages should have only a single changelog entry closing the <link linkend="itp-rfp-reports">ITP bug</link>. Indeed, when a package is submitted only
+          the latest paragraph is parsed by the Debian bug tracking system. Therefore do not add new changelog entries when updating an unrealeased
+          package, the VCS logs are enough to track the changes.
+      </para>
+      <para>When a sponsor is uploading a package for you, mark the package <varname>target</varname> as UNRELEASED. The sponsor will change it
+            as appropriate before uploading the package.
+      </para>
+    </sect2>
+    <sect2>
       <title><filename>debian/control</filename></title>
       <sect3>
 	<title><varname>Section</varname> and <filename>Priority</filename> Fields</title>
@@ -235,7 +250,7 @@ $ chmod 0775 hooks/post-receive
 	<title>Metapackages</title>
 	<para>&DebSci; is also managing the Debian-Science metapackages. Consequently, please update the appropriate metapackage with your new package as described in <link linkend="management-of-the-debian-science-metapackages">Chapter 2</link>.</para>
 	</sect1>
-  <sect1>
+  <sect1 id="itp-rfp-reports">
     <title>ITP/RFP reports</title>
 	  <sect2>
 	    <title>Intend To Package (ITP)</title>

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/policy.git