<!entity % commondata SYSTEM "common.ent" > %commondata;
<!-- CVS revision of this document -->
- <!entity cvs-rev "$Revision: 1.181 $">
+ <!entity cvs-rev "$Revision: 1.187 $">
<!-- if you are translating this document, please notate the CVS
revision of the developers reference here -->
<!--
<sect id="bpp-debian-control">
<heading>Best practices for <file>debian/control</file></heading>
<p>
-The following practices supplement the <url
- id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
- name="Policy on package descriptions">.</p>
+The following practices are relevant to the
+<file>debian/control</file> file. They supplement the <url
+id="&url-debian-policy;ch-miscellaneous.html#s-descriptions"
+name="Policy on package descriptions">.
+ <p>
+The description of the package, as defined by the corresponding field
+in the <file>control</file> file, contains both the package synopsis
+and the long description for the package.
+
+
+
+ <sect1 id="bpp-desc-basics">
+ <heading>General guidelines for package descriptions</heading>
+ <p>
+The package description should be written for the average likely user,
+the average person who will use and benefit from the package. For
+instance, development packages are for developers, and can be
+technical in their language. More general-purpose applications, such
+as editors, should be written for a less technical user.
+ <p>
+Our review of package descriptions lead us to conclude that most
+package descriptions are technical, that is, are not written to make
+sense for non-technical users. Unless your package really is only for
+technical users, this is a problem.
+ <p>
+How do you write for non-technical users? Avoid jargon. Avoid
+referring to other applications or frameworks that the user might not
+be familiar with — "GNOME" or "KDE" is fine, but "GTK+" is
+probably not. Try not to assume any knowledge at all. If you must
+use technical terms, introduce them.
+ <p>
+References to the names of any other software packages, protocol names,
+standards, or specifications should use their canonical forms, if one
+exists. For example, use "X Window System", "X11", or "X"; not "X
+Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk".
+Use "GNOME", not "Gnome". Use "PostScript", not "Postscript" or
+"postscript".
+
+
+ <sect1 id="bpp-pkg-synopsis">
+ <heading>The package synopsis, or short description</heading>
+ <p>
+The synopsis line (the short description) should be concise. It
+must not repeat the package's name (this is policy).
+ <p>
+It's a good idea to think of the synopsis as an appositive clause, not
+a full sentence. An appositive clause is defined in WordNet as a
+grammatical relation between a word and a noun phrase that follows,
+e.g., "Rudolph the red-nosed reindeer". The appositive clause here is
+"red-nosed reindeer". Since the synopsis is a clause, rather than a
+full sentence, we recommend that it neither start with a capital nor
+end with a full stop (period). Imagine that the synopsis is combined
+with the package name in the following way:
+
+<example>The <var>package-name</var> is a <var>synopsis</var>.</example>
+ <p>
+If the package name is an acronym, it is sometimes useful to expand
+the acronym. For instance, the synopsis for <package>vim</package> is
+"Vi IMproved - enhanced vi editor".
+
<sect1 id="bpp-pkg-desc">
- <heading>Writing useful descriptions</heading>
+ <heading>The long description</heading>
<p>
-The description of the package (as defined by the corresponding field
-in the <file>control</file> file) is the primary information available
-to the user about a package before they install it. It should provide
-all the required information to let the user decide whether to install
-the package.
+The long description is the primary information available to the user
+about a package before they install it. It should provide all the
+information needed to let the user decide whether to install the
+package. Assume that the user has already read the package synopsis.
<p>
-The following practices supplement the <url name="Policy on the descriptions
-of packages" id="&url-debian-policy;ch-miscellaneous.html#s-descriptions">.
+The long description should consist of full and complete sentences.
+It is recommended to use two spaces after full stops in sentences. We
+realize this is an American style rather than European, but it is
+additionally helpful in creating visual space in fixed-width fonts.
<p>
-The synopsis line (the short description) should primarily be concise.
-You may capitalize the first letter for aesthetics. It is customary to
-make the synopsis an appositive clause (not a full sentence) in which
-case there's no need to put a full stop (period) at the end.
+The first paragraph of the long description should answer the
+following questions: what does the package do? what task does it help
+the user accomplish? It is important to describe this in a
+non-technical way, unless of course the audience for the package is
+necessarily technical.
<p>
-The long description should, however, always consist of full sentences.
+The following paragraphs should answer the following questions: Why do
+I as a user need this package? What other features does the package
+have? What outstanding features and deficiencies are there compared
+to other packages (e.g., "if you need X, use Y instead")? Is this
+package related to other packages in some way that is not handled by
+the package manager (e.g., "this is the client to the foo server")?
<p>
-Since the first user impression is based on the description, be
-careful to avoid spelling and grammar mistakes. Ensure that you
+Be careful to avoid spelling and grammar mistakes. Ensure that you
spell-check it. <prgn>ispell</prgn> has a special <tt>-g</tt> option
for <file>debian/control</file> files:
<example>ispell -d american -g debian/control</example>
-If you want someone to proofread the description that you
-intend to use you may ask on &email-debian-l10n-english;.
</sect1>
<sect1 id="bpp-upstream-info">
</sect1>
</sect>
+
+ <sect id="bpp-debian-changelog">
+ <heading>Best practices for <file>debian/changelog</file></heading>
+ <p>
+The following practices supplement the <url name="Policy on changelog
+files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
+
+ <sect1 id="bpp-changelog-do">
+ <heading>Writing useful changelog entries</heading>
+ <p>
+The changelog entry for a package revision documents changes in that
+revision, and only them. Concentrate on describing significant and
+user-visible changes that were made since the last version.
+ <p>
+Focus on <em>what</em> was changed — who, how and when are
+usually less important. Having said that, remember to politely
+attribute people who have provided notable help in making the package
+(e.g., those who have sent in patches).
+ <p>
+There's no need to elaborate the trivial and obvious changes. You can
+also aggregate several changes in one entry. On the other hand, don't
+be overly terse if you have undertaken a major change. Be especially
+clear if there are changes that affect the behaviour of the program.
+For further explanations, use the <file>README.Debian</file> file.
+ <p>
+Use common English so that the majority of readers can comprehend it.
+Avoid abbreviations, "tech-speak" and jargon when explaining changes
+that close bugs, especially for bugs filed by users that did not
+strike you as particularly technically savvy. Be polite, don't swear.
+ <p>
+It is sometimes desirable to prefix changelog entries with the names
+of the files that were changed. However, there's no need to
+explicitly list each and every last one of the changed files,
+especially if the change was small or repetitive. You may use
+wildcards.
+ <p>
+When referring to bugs, don't assume anything. Say what the problem
+was, how it was fixed, and append the "closes: #nnnnn" string. See
+<ref id="upload-bugfix"> for more information.
+
+
+ <sect1 id="bpp-changelog-misconceptions">
+ <heading>Common misconceptions about changelog entries</heading>
+ <p>
+The changelog entries should <strong>not</strong> document generic
+packaging issues ("Hey, if you're looking for foo.conf, it's in
+/etc/blah/."), since administrators and users are supposed to be at
+least remotely acquainted with how such things are generally arranged
+on Debian systems. Do, however, mention if you change the location of
+a configuration file.
+ <p>
+The only bugs closed with a changelog entry should be those that are
+actually fixed in the same package revision. Closing unrelated bugs
+in the changelog is bad practice. See <ref id="upload-bugfix">.
+ <p>
+The changelog entries should <strong>not</strong> be used for random
+discussion with bug reporters ("I don't see segfaults when starting
+foo with option bar; send in more info"), general statements on life,
+the universe and everything ("sorry this upload took me so long, but I
+caught the flu"), or pleas for help ("the bug list on this package is
+huge, please lend me a hand"). Such things usually won't be noticed
+by their target audience, but may annoy people who wish to read
+information about actual changes in the package. See <ref
+id="bug-answering"> for more information on how to use the bug
+tracking system.
+ <p>
+It is an old tradition to acknowledge bugs fixed in non-maintainer
+uploads in the first changelog entry of the proper maintainer upload,
+for instance, in a changelog entry like this:
+<example>
+ * Maintainer upload, closes: #42345, #44484, #42444.
+</example>
+This will close the NMU bugs tagged "fixed" when the package makes
+it into the archive. The bug for the fact that an NMU was done can be
+closed the same way. Of course, it's also perfectly acceptable to
+close NMU-fixed bugs by other means; see <ref id="bug-answering">.
+ </sect1>
+
+ <sect1 id="bpp-changelog-errors">
+ <heading>Common errors in changelog entries</heading>
+ <p>
+The following examples demonstrate some common errors or example of
+bad style in changelog entries.
+
+ <p>
+<example>
+ * Fixed all outstanding bugs.
+</example>
+This doesn't tell readers anything too useful, obviously.
+
+ <p>
+<example>
+ * Applied patch from Jane Random.
+</example>
+What was the patch about?
+
+ <p>
+<example>
+ * Late night install target overhaul.
+</example>
+Overhaul which accomplished what? Is the mention of late night
+supposed to remind us that we shouldn't trust that code?
+
+ <p>
+<example>
+ * Fix vsync FU w/ ancient CRTs.
+</example>
+Too many acronyms, and it's not overly clear what the, uh, fsckup (oops,
+a curse word!) was actually about, or how it was fixed.
+
+ <p>
+<example>
+ * This is not a bug, closes: #nnnnnn.
+</example>
+First of all, there's absolutely no need to upload the package to
+convey this information; instead, use the bug tracking system.
+Secondly, there's no explanation as to why the report is not a bug.
+
+ <p>
+<example>
+ * Has been fixed for ages, but I forgot to close; closes: #54321.
+</example>
+If for some reason you didn't mention the bug number in a previous changelog
+entry, there's no problem, just close the bug normally in the BTS. There's
+no need to touch the changelog file, presuming the description of the fix is
+already in (this applies to the fixes by the upstream authors/maintainers as
+well, you don't have to track bugs that they fixed ages ago in your
+changelog).
+
+ <p>
+<example>
+ * Closes: #12345, #12346, #15432
+</example>
+Where's the description? If you can't think of a descriptive message,
+start by inserting the title of each different bug.
+ </sect1>
+ </sect>
+
<!--
<sect1 id="pkg-mgmt-cvs">Managing a package with CVS
<p>
sympa may be an example package
-->
- <sect1 id="bpp-archindepdata">Architecture-independent data
- <p>
- It is not uncommon to have a large amount of architecture-independent
- data packaged with a program. For example, collection of icons,
- wallpapers or other graphic files, or audio files. If the size of
- this data is negligible compared to the size of the remainder of the
- package, you can keep it all in the same package.
-
- <p>
- However, if the size of the data is considerable, consider splitting
- it out into a separate, architecture-independent package
- ("_all.deb"). By doing this, you avoid needless duplication of the
- same data into eleven or more .debs per each architecture. While
- this adds some extra overhead into the Packages files, it can save a
- lot of disk space on Debian mirrors, and it also reduces processing
- time of Lintian or Linda when run over the entire Debian archive.
- </sect1>
-
- </sect>
-
- <sect id="bpp-debian-changelog">
- <heading>Best practices for <file>debian/changelog</file></heading>
- <p>
-The following practices supplement the <url name="Policy on changelog
-files" id="&url-debian-policy;ch-docs.html#s-changelogs">.</p>
-
- <sect1 id="bpp-changelog-do">
- <heading>Writing useful changelog entries</heading>
- <p>
-The changelog entry for a package revision documents changes in that
-revision, and only them. Concentrate on describing significant and
-user-visible changes that were made since the last version.
- <p>
-Focus on <em>what</em> was changed — who, how and when are
-usually less important. Having said that, remember to politely
-attribute people who have provided notable help in making the package
-(e.g., those who have sent in patches).
+ <sect1 id="bpp-archindepdata">
+ <heading>Architecture-independent data</heading>
<p>
-There's no need to elaborate the trivial and obvious changes. You can
-also aggregate several changes in one entry. On the other hand, don't
-be overly terse if you have undertaken a major change. Be especially
-clear if there are changes that affect the behaviour of the program.
-For further explanations, use the <file>README.Debian</file> file.
+It is not uncommon to have a large amount of architecture-independent
+data packaged with a program. For example, audio files, a collection
+of icons, wallpaper patterns, or other graphic files. If the size of
+this data is negligible compared to the size of the rest of the
+package, it's probably best to keep it all in a single package.
<p>
-Use common English so that the majority of readers can comprehend it.
-Avoid abbreviations, "tech-speak" and jargon when explaining changes
-that close bugs, especially for bugs filed by users that did not
-strike you as particularly technically savvy. Be polite, don't swear.
- <p>
-It is sometimes desirable to prefix changelog entries with the names
-of the files that were changed. However, there's no need to
-explicitly list each and every last one of the changed files,
-especially if the change was small or repetitive. You may use
-wildcards.
- <p>
-When referring to bugs, don't assume anything. Say what the problem
-was, how it was fixed, and append the "closes: #nnnnn" string. See
-<ref id="upload-bugfix"> for more information.
-
-
- <sect1 id="bpp-changelog-misconceptions">
- <heading>Common misconceptions about changelog entries</heading>
- <p>
-The changelog entries should <strong>not</strong> document generic
-packaging issues ("Hey, if you're looking for foo.conf, it's in
-/etc/blah/."), since administrators and users are supposed to be at
-least remotely acquainted with how such things are generally arranged
-on Debian systems. Do, however, mention if you change the location of
-a configuration file.
- <p>
-The only bugs closed with a changelog entry should be those that are
-actually fixed in the same package revision. Closing unrelated bugs
-in the changelog is bad practice. See <ref id="upload-bugfix">.
- <p>
-The changelog entries should <strong>not</strong> be used for random
-discussion with bug reporters ("I don't see segfaults when starting
-foo with option bar; send in more info"), general statements on life,
-the universe and everything ("sorry this upload took me so long, but I
-caught the flu"), or pleas for help ("the bug list on this package is
-huge, please lend me a hand"). Such things usually won't be noticed
-by their target audience, but may annoy people who wish to read
-information about actual changes in the package. See <ref
-id="bug-answering"> for more information on how to use the bug
-tracking system.
- <p>
-It is an old tradition to acknowledge bugs fixed in non-maintainer
-uploads in the first changelog entry of the proper maintainer upload,
-for instance, in a changelog entry like this:
-<example>
- * Maintainer upload, closes: #42345, #44484, #42444.
-</example>
-This will close the NMU bugs in "fixed" state when the package makes
-it into the archive (and also the bug for the fact that an NMU was
-done). It is also perfectly acceptable to close NMU-fixed bugs by
-other means; see <ref id="bug-answering">.
- <p>
-Changelogs shouldn't include general statements on life, the universe
-and everything ("sorry this upload took me so long, but I caught the
-flu"). Exceptions can be made if the comment is funny ;-) Obviously,
-this is subjective, so it's likely best if it's kept out of technical
-documentation such as changelogs.
- </sect1>
-
- <sect1 id="bpp-changelog-errors">
- <heading>Common errors in changelog entries</heading>
- <p>
-The following examples demonstrate some common errors or example of
-bad style in changelog entries.
-
- <p>
-<example>
- * Fixed all outstanding bugs.
-</example>
-This doesn't tell readers anything too useful, obviously.
-
- <p>
-<example>
- * Applied patch from Jane Random.
-</example>
-What was the patch about?
-
- <p>
-<example>
- * Late night install target overhaul.
-</example>
-Overhaul which accomplished what? Is the mention of late night
-supposed to remind us that we shouldn't trust that code?
-
- <p>
-<example>
- * Fix vsync FU w/ ancient CRTs.
-</example>
-Too many acronyms, and it's not overly clear what the, uh, fsckup (oops,
-a curse word!) was actually about, or how it was fixed.
-
- <p>
-<example>
- * This is not a bug, closes: #nnnnnn.
-</example>
-First of all, there's absolutely no need to upload the package to
-convey this information; instead, use the bug tracking system.
-Secondly, there's no explanation as to why the report is not a bug.
-
- <p>
-<example>
- * Has been fixed for ages, but I forgot to close; closes: #54321.
-</example>
-If for some reason you didn't mention the bug number in a previous changelog
-entry, there's no problem, just close the bug normally in the BTS. There's
-no need to touch the changelog file, presuming the description of the fix is
-already in (this applies to the fixes by the upstream authors/maintainers as
-well, you don't have to track bugs that they fixed ages ago in your
-changelog).
-
- <p>
-<example>
- * Closes: #12345, #12346, #15432
-</example>
-Where's the description? If you can't think of a descriptive message,
-start by inserting the title of each different bug.
+However, if the size of the data is considerable, consider splitting
+it out into a separate, architecture-independent package ("_all.deb").
+By doing this, you avoid needless duplication of the same data into
+eleven or more .debs, one per each architecture. While this
+adds some extra overhead into the <file>Packages</file> files, it
+saves a lot of disk space on Debian mirrors. Separating out
+architecture-independent data also reduces processing time of
+<prgn>lintian</prgn> or <prgn>linda</prgn> (see <ref id="tools-lint">)
+when run over the entire Debian archive.
</sect1>
</sect>
+
</chapt>
~ianmdlvl / developers-reference.git / blobdiff