- Added best packaging practices chapter.

- Added "Writing useful descriptions" as a first entry in that
  chapter. Closes: #53109, #129848

git-svn-id: svn://anonscm.debian.org/ddp/manuals/trunk/developers-reference@1670 313b444b-1b9f-4f58-a734-7bb04f332e8d

diff --git a/debian/changelog b/debian/changelog
index 87a82ce2ecc87b1a12f9c2d5423988ce2b0bc79a..fa2a9fd007e4994ab3b65386c0dd83acf4d9818d 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -47,6 +47,9 @@ developers-reference (3.0) unstable; urgency=low
     - clarify wording between "porter upload", "binary-only NMU", "simple
       recompile"; closes: #102626
     - extended "removing a package"; closes: #135560
+    - Added best packaging practices chapter.
+    - Added "Writing useful descriptions" as a first entry in that
+      chapter. Closes: #53109, #129848
 
   * Antoine Hulin:
     - update French translation

diff --git a/developers-reference.sgml b/developers-reference.sgml
index 1f483c92f914f9ef559f2a35f0b66b75b8a19804..b93f6b3e9c023773291aa7bf110f437d10098da1 100644 (file)
--- a/developers-reference.sgml
+++ b/developers-reference.sgml
@@ -6,7 +6,7 @@
   <!entity % commondata  SYSTEM "common.ent" > %commondata;
 
   <!-- CVS revision of this document -->
-  <!entity cvs-rev "$Revision: 1.97 $">
+  <!entity cvs-rev "$Revision: 1.98 $">
   <!-- if you are translating this document, please notate the CVS
        revision of the developers reference here -->
   <!--
@@ -2091,6 +2091,39 @@ latest version of the distribution (usually from 'unstable') using the
 latest <package>lintian</package>.
 
 
+  <chapt id="best-pkging-practices">
+    <heading>Best Packaging Practices</heading>
+    <p>
+Debian's quality is largely due to its Policy that all packages
+follow. But it's also because we accumulated years of experience
+in packaging; very talented people created great tools to make
+good packages without much troubles.
+    <p>
+This chapter provides the best known solutions to common problems
+faced during packaging. It also lists various advice collected on
+several mailing lists. By following them, you will make Debian's quality
+even better.
+
+    <sect id="misc-advice">
+       <heading>Miscellaenous advice</heading>
+
+       <sect1 id="writing-desc">
+           <heading>Writing useful descriptions</heading>
+           <p>
+The description of the package (as defined by the corresponding field
+in the <file>control</file> file) is usually the first information
+available to the user before he installs it. As such, it should
+provide all the required information that can help him decide whether
+or not he will install it.
+           <p>
+For example, apart from the usual description that you will copy from the
+upstream <file>README</file>, you should include the URL of the
+website if there's any. If the package is not yet considered stable
+by the author, you may also want to warn the user that the
+package is not ready for production use.
+
+
+
   <chapt id="beyond-pkging">
     <heading>Beyond Packaging</heading>
     <p>