description.desc 9.5 KB
Newer Older
1 2 3
Check-Script: description
Author: Christian Schwarz <schwarz@debian.org>
Abbrev: des
4
Type: binary, udeb
5
Needs-Info: unpacked
6 7
Info: Check if the Description control field of a binary package conforms
 to the rules in the Policy Manual (section 3.4).
8 9

Tag: package-has-no-description
10 11
Severity: serious
Certainty: certain
12
Info: The binary package does not have a "Description:" control field.
13
Ref: policy 3.4
14 15

Tag: description-synopsis-is-empty
16 17
Severity: serious
Certainty: certain
18
Info: The first line in the "Description:" is empty.
19
Ref: policy 3.4
20

21 22 23 24 25 26
Tag: extended-description-contains-empty-paragraph
Severity: normal
Certainty: certain
Info: The extended description (the lines after the first line of the
 "Description:" field) contains an empty paragraph.

27
Tag: extended-description-is-empty
28 29
Severity: serious
Certainty: certain
30 31
Info: The extended description (the lines after the first line of the
 "Description:" field) is empty.
32
Ref: policy 3.4
33

34 35 36 37 38 39 40
Tag: description-too-short
Severity: serious
Certainty: certain
Ref: devref 6.2.2
Info: The description contains only a single word. It is likely that the
 description won't be very clear for the user.

41 42 43 44
Tag: description-is-pkg-name
Severity: serious
Certainty: certain
Ref: devref 6.2.2
45 46
Info: The description is the same as the package name.
 A better description should be provided for the user.
47

48 49 50 51 52
Tag: extended-description-is-probably-too-short
Severity: minor
Certainty: possible
Ref: devref 6.2.1, devref 6.2.3
Info: The extended description (the lines after the first line of the
53
 "Description:" field) is only one or two lines long. The extended
54 55
 description should provide a user with enough information to decide
 whether they want to install this package, what it contains, and how it
56
 compares to similar packages. One or two lines is normally not enough to
57 58
 do this.

59
Tag: description-contains-invalid-control-statement
60 61
Severity: serious
Certainty: certain
62 63
Info: The description contains an invalid control statement.
 .
64
 A control statement is a line starting with a dot (.). The only
65 66 67 68
 control statement is defined by the policy is a single dot denoting
 an empty line.
 .
 The "empty-line" control statement does not permit any characters
69
 following it on the same line. Therefore, the line must consist
70
 entirely of a space followed by a dot.
71
Ref: policy 5.6.13
72 73

Tag: description-too-long
74
Severity: minor
75
Certainty: certain
76
Info: The first line of the "Description:" must be less than 80 characters.
77
Ref: policy 3.4.1
78 79

Tag: description-starts-with-package-name
80 81
Severity: important
Certainty: certain
82 83
Info: The first line of the "Description:" should not start with the
 package name. For example, the package <tt>foo</tt> should not
Russ Allbery's avatar
Russ Allbery committed
84
 have a description like this: "foo is a program that...".
85
Ref: policy 3.4.1
86

87 88 89 90 91 92 93 94 95 96 97
Tag: description-synopsis-starts-with-article
Severity: minor
Certainty: certain
Info: The first line of the "Description:" should omit any initial indefinite
 or definite article: "a", "an", or "the". A good heuristic is that it should
 be possible to substitute the package <tt>name</tt> and <tt>synopsis</tt>
 into this formula:
 .
 The package <tt>name</tt> provides {a,an,the,some} <tt>synopsis</tt>.
Ref: devref 6.2.2

98
Tag: description-contains-tabs
99 100
Severity: important
Certainty: certain
101
Info: The package "Description:" must not contain tab characters.
102
Ref: policy 5.6.13
103 104

Tag: description-starts-with-leading-spaces
105 106
Severity: normal
Certainty: possible
107 108 109 110
Info: The package's extended "Description:" paragraph starts with more than
 one leading space. Usually, leading spaces are used to switch "verbatim
 display" on (i.e., lines are not wrapped) so this might be a bug in the
 package.
111 112

Tag: possible-unindented-list-in-extended-description
113 114
Severity: normal
Certainty: possible
115 116 117 118
Info: The package "Description:" contains an unindented line which
 starts with a dash (-) or asterisk (*). If this was meant to be a
 list of items these lines need to be indented (dselect would
 word-wrap these lines otherwise).
119
Ref: policy 5.6.13
120 121

Tag: description-is-debmake-template
122 123
Severity: important
Certainty: certain
124 125 126 127
Info: The synopsis or the extended description just says "Missing",
 which is a template provided by debmake.

Tag: description-is-dh_make-template
128
Severity: serious
129
Certainty: certain
130 131 132
Info: The synopsis or the extended description has not been changed
 from the template provided by dh_make.

133 134 135 136
Tag: description-contains-dh-make-perl-template
Severity: normal
Certainty: certain
Info: The extended description contains the statement that it was
137
 automagically extracted by dh-make-perl. Please check the description
138 139 140
 for correctness and usefulness and remove the dh-make-perl statement
 to signal that you have done so. 

141
Tag: description-synopsis-might-not-be-phrased-properly
142
Severity: minor
143
Certainty: possible
144 145 146
Info: The package synopsis (also known as the "short" description, ie. the
 first line in the package's "Description:" field) either ends with a full
 stop "." character or starts another sentence.
147
 .
148
 This is not necessary as the synopsis does not need to be a full
149
 sentence. It is recommended that a single descriptive phrase is used
150 151 152 153
 instead.
 .
 Note also that the synopsis is not part of the rest of the "long"
 Description: field.
154
Ref: devref 6.2.2
155 156

Tag: description-synopsis-is-duplicated
157 158
Severity: important
Certainty: certain
159 160 161
Info: The first line of the extended Description: should not repeat the
 synopsis exactly. This indicates that either the synopsis is badly formed
 or that the extended description has been wrongly copied and pasted.
162
Ref: policy 3.4.2
163

164 165 166
Tag: spelling-error-in-description-synopsis
Severity: minor
Certainty: certain
167 168 169
Info: Lintian found a spelling error in the package synopsis. Lintian
 has a list of common misspellings that it looks for. It does not have a
 dictionary like a spelling checker does. It is particularly picky about
170 171 172 173 174 175 176
 spelling and capitalization in package descriptions since they're very
 visible to end users.

Tag: capitalization-error-in-description-synopsis
Severity: minor
Certainty: wild-guess
Info: Lintian found a possible capitalization error in the package
177 178
 synopsis. Lintian has a list of common capitalization errors,
 primarily of upstream projects, that it looks for. It does not have a
179 180
 dictionary like a spelling checker does.

181
Tag: extended-description-line-too-long
182 183
Severity: normal
Certainty: certain
184 185 186 187
Info: One or more lines in the extended part of the "Description:" field
 have been found to contain more than 80 characters. For the benefit of
 users of 80x25 terminals, it is recommended that the lines do not exceed
 80 characters.
188
Ref: policy 3.4.1
189 190

Tag: description-contains-homepage
191 192
Severity: normal
Certainty: certain
193 194 195 196 197 198
Info: The extended description contains a "Homepage" pseudo-field
 following the old Developer's Reference recommendation. As of 1.14.6,
 dpkg now supports Homepage as a regular field in
 <tt>debian/control</tt>. This pseudo-field should be moved from the
 extended description to the fields for the relevant source or binary
 packages.
199 200

Tag: spelling-error-in-description
201
Severity: minor
202
Certainty: certain
203 204 205
Info: Lintian found a spelling error in the package description. Lintian
 has a list of common misspellings that it looks for. It does not have a
 dictionary like a spelling checker does. It is particularly picky about
206 207 208 209 210 211 212
 spelling and capitalization in package descriptions since they're very
 visible to end users.

Tag: capitalization-error-in-description
Severity: minor
Certainty: wild-guess
Info: Lintian found a possible capitalization error in the package
213 214
 description. Lintian has a list of common capitalization errors,
 primarily of upstream projects, that it looks for. It does not have a
215 216 217 218 219 220
 dictionary like a spelling checker does.
 .
 This is a particularly picky check of capitalization in package
 descriptions, since they're very visible to end users, but it will have
 false positives for project names used in a context where they should be
 lowercase, such as package names or executable names.
221

222 223 224 225
Tag: using-first-person-in-description
Severity: minor
Certainty: possible
Info: You should avoid the use of first person ("I will do this..." or
226 227
 "We recommend..."). The computer is not a person and the description
 does not speak for the maintainer or maintainers. Instead, use a more
228 229 230 231 232 233
 neutral construction and try to rephrase into factual statements about
 the package.
 .
 For example, rather than saying "I don't recommend this package if you
 are short on memory," say something like "this package is not suitable
 for low-memory systems."
234 235

Tag: description-possibly-contains-homepage
236 237
Severity: wishlist
Certainty: wild-guess
238
Info: This package has no Homepage field but has a URL in the description
239
 and wording that might indicate this is the package Homepage. If it is,
240 241
 add a Homepage control field containing it rather than mentioning it in
 the package description.
242

243
# Imported from pkg-perl-tools (named no-module-name-in-description there)
244 245 246 247 248 249 250
Tag: perl-module-name-not-mentioned-in-description
Severity: minor
Certainty: certain
Experimental: yes
Info: Debian users are likely to look for perl modules by their name, e.g.
 Foo::Bar, not by package name (libfoo-bar-perl). To make this easier, the main
 module name should be present in the long package description.
251 252 253 254 255 256 257

Tag: description-mentions-planned-features
Severity: wishlist
Certainty: wild-guess
Info: This package appears to mention planned or upcoming features of
 the software.
 .
258 259 260
 Package descriptions should not mention features that are not yet implemented
 as they waste the time of people searching for particular keywords. They are
 also liable to become outdated quickly.
261 262
 .
 Please remove such statements from the package description.