From: hertzog <hertzog@313b444b-1b9f-4f58-a734-7bb04f332e8d>
Date: Wed, 8 May 2002 10:29:20 +0000 (+0000)
Subject: - Added best packaging practices chapter.
X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?a=commitdiff_plain;h=3b99d1b9e1df05d1f610146e6a2192cd1f38b5f3;p=developers-reference.git

- 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 87a82ce..fa2a9fd 100644
--- 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 1f483c9..b93f6b3 100644
--- 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>