1 Check-Script: changelog-file
2 Author: Christian Schwarz <schwarz@debian.org>
6 Needs-Info: file-info, changelog-file
7 Info: This script checks if a binary package conforms to policy
8 with regards to changelog files.
10 Each binary package with a /usr/share/doc/<foo> directory must have
11 a Debian changelog file in "changelog.Debian.gz" unless the Debian
12 changelog and the upstream one is the same file; in this case, it
13 must be in "changelog.gz".
15 If there is an upstream changelog file, it must be named
18 Both changelog files should be compressed using "gzip -9".
19 Even if they start out small, they will become large with time.
21 Tag: html-changelog-without-text-version
24 Info: If the upstream changelog file is HTML formatted, a text version
25 should also be accessible as "changelog.gz". (This can be created by
29 Tag: changelog-file-not-compressed
32 Info: Changelog files should be compressed using "gzip -9". Even if they
33 start out small, they will become large with time.
36 Tag: debian-news-file-not-compressed
39 Info: NEWS.Debian files should be compressed using "gzip -9". The file
40 must always have the same name.
43 Tag: changelog-not-compressed-with-max-compression
46 Info: Changelog files should be compressed using "gzip -9"; i.e., using
47 the maximum compression level via the -9 option to gzip.
50 Tag: wrong-name-for-changelog-of-native-package
53 Info: The changelog file of a native Debian package (i.e., if there is
54 no upstream source) should usually be installed as
55 /usr/share/doc/<i>pkg</i>/changelog.gz
58 Tag: changelog-file-missing-in-native-package
61 Info: Each Debian package (which provides a /usr/share/doc/<i>pkg</i>
62 directory) has to install a changelog file. Since this package seems
63 to be a native Debian package (i.e., there is no upstream source),
64 the file should usually be installed as
65 /usr/share/doc/<i>pkg</i>/changelog.gz
68 Tag: wrong-name-for-upstream-changelog
71 Info: If there is an upstream changelog file, it should usually be
72 installed as /usr/share/doc/<i>pkg</i>/changelog.gz
75 Tag: no-upstream-changelog
78 Info: The package does not install an upstream changelog file. If upstream
79 provides a changelog, it should be accessible as
80 <tt>/usr/share/doc/<i>pkg</i>/changelog.gz</tt>.
82 It's currently unclear how best to handle multiple binary packages from
83 the same source. Some maintainers put a copy of the upstream changelog
84 in each package, but it can be quite long. Some include it in one
85 package and add symlinks to the other packages, but this requires there
86 be dependencies between the packages. Some only include it in a "central"
87 binary package and omit it from more ancillary packages.
90 Tag: wrong-name-for-debian-changelog-file
93 Info: The Debian changelog file should usually be installed as
94 /usr/share/doc/<i>pkg</i>/changelog.Debian.gz
97 Tag: wrong-name-for-debian-news-file
100 Info: The Debian news file must be installed as
101 /usr/share/doc/<i>pkg</i>/NEWS.Debian.gz with exactly that capitalization
102 or automated tools may not find it correctly.
105 Tag: debian-changelog-file-missing
108 Info: Each Debian package (which provides a /usr/share/doc/<i>pkg</i>
109 directory) has to install a Debian changelog file
110 /usr/share/doc/<i>pkg</i>/changelog.Debian.gz
113 Tag: debian-changelog-file-is-a-symlink
116 Info: The Debian changelog file is a symlink to a file in a different
117 directory or not found in this package. Please don't do this. It makes
118 package checking and manipulation unnecessarily difficult. Because it was
119 a symlink, the Debian changelog file was not checked for other
120 problems. (Symlinks to another file in /usr/share/doc/<i>pkg</i> or a
121 subdirectory thereof are fine and should not trigger this warning.)
123 To refer to the changelog, copyright, and other documentation files of
124 another package that this one depends on, please symlink the entire
125 /usr/share/doc/<i>pkg</i> directory rather than individual files.
127 Tag: debian-changelog-file-missing-or-wrong-name
130 Info: Each Debian package (which provides a /usr/share/doc/<i>pkg</i>
131 directory) must install a Debian changelog file in
132 /usr/share/doc/<i>pkg</i>/changelog.Debian.gz
134 A common error is to name the Debian changelog like an upstream changelog
135 (/usr/share/doc/<i>pkg</i>/changelog.gz); therefore, lintian will apply
136 further checks to such a file if it exists even after issuing this error.
139 Tag: debian-changelog-file-contains-obsolete-user-emacs-settings
142 Info: The add-log-mailing-address variable is no longer honored in
143 debian-changelog-mode, and should not appear in packages' changelog
144 files. Instead, put something like this in your ~/.emacs:
146 (setq debian-changelog-mailing-address "userid@debian.org")
148 Tag: debian-changelog-file-contains-debmake-default-email-address
151 Info: The changelog file contains an email address (<..@unknown>)
152 that was not updated to the maintainer's real address.
154 Tag: debian-changelog-file-contains-invalid-email-address
157 Info: The changelog file contains an invalid email address: the domain
158 needs at least one dot. This looks like a mistake.
160 Tag: debian-changelog-file-uses-obsolete-national-encoding
164 Info: The Debian changelog file must be valid UTF-8, an encoding of
165 the Unicode character set.
167 There are many ways to convert a changelog from an obsoleted encoding
168 like ISO-8859-1; you may for example use "iconv" like:
170 $ iconv -f ISO-8859-1 -t UTF-8 changelog > changelog.new
171 $ mv changelog.new changelog
173 Tag: debian-news-file-uses-obsolete-national-encoding
176 Info: The NEWS.Debian file must be valid UTF-8, an encoding of the Unicode
179 There are many ways to convert a changelog from an obsoleted encoding
180 like ISO-8859-1; you may for example use "iconv" like:
182 $ iconv -f ISO-8859-1 -t UTF-8 NEWS.Debian > NEWS.Debian.new
183 $ mv NEWS.Debian.new NEWS.Debian
185 Tag: latest-debian-changelog-entry-without-new-date
188 Info: The latest Debian changelog entry has either the same or even an
189 older date as the entry before.
191 Tag: latest-debian-changelog-entry-without-new-version
194 Info: The latest Debian changelog entry has a version number that's either
195 the same or smaller than the version number of the entry before.
197 Tag: latest-debian-changelog-entry-changed-to-native
200 Info: The latest package has a Debian native version number, while the
201 previous version number was not native. This is usually a mistake made by
202 the maintainer by forgetting to append -1 when uploading a new upstream
205 Tag: experimental-to-unstable-without-comment
208 Info: The previous version of this package had a distribution of
209 experimental, this version has a distribution of unstable, and there's
210 apparently no comment about the change of distributions (Maemian looks
211 for the phrase "to unstable"). This may indicate a mistake in setting
212 the distribution and accidentally uploading to unstable a package
213 intended for experimental.
215 Tag: syntax-error-in-debian-changelog
218 Info: While parsing the Debian changelog, a syntax error was found.
221 Tag: syntax-error-in-debian-news-file
224 Info: While parsing the NEWS.Debian file, a syntax error was found.
227 Tag: improbable-bug-number-in-closes
230 Info: The most recent changelog closes a bug numbered less than 100.
231 While this is distantly possible, it's more likely a typo or a
232 placeholder value that mistakenly wasn't filled in.
234 Tag: wrong-bug-number-in-closes
237 Info: Bug numbers can only contain digits.
240 Tag: possible-missing-colon-in-closes
243 Info: To close a bug in the Debian changelog, the word "closes" must be
244 followed by a colon. This entry looked like it was intended to close a
245 bug, but there's no colon after "closes".
248 Tag: debian-news-entry-has-strange-distribution
251 Info: The latest entry in NEWS.Debian has an unusual distribution name.
252 This field is ignored by the archive software, so its value doesn't truly
253 matter, but it may be confusing to users reading the entry if the
254 distribution doesn't match the distribution for the same entry in the
255 Debian changelog file.
257 Tag: spelling-error-in-changelog
260 Info: Maemian found a spelling error in the latest entry of the Debian
261 changelog. Maemian has a list of common misspellings that it looks for.
262 It does not have a dictionary like a spelling checker does.
264 When writing a changelog entry for a spelling fix that includes the
265 misspelling, ensure the word "spelling" is on the same line as the
266 misspelled word to avoid triggering this warning.
268 Tag: spelling-error-in-news-debian
271 Info: Maemian found a spelling error in the latest entry of the
272 NEWS.Debian file. Maemian has a list of common misspellings that it
273 looks for. It does not have a dictionary like a spelling checker does.
275 Tag: new-package-should-close-itp-bug
278 Info: This package appears to be the first packaging of a new upstream
279 software package (there is only one changelog entry and the Debian
280 revision is 1), but it does not close any bugs. The initial upload of a
281 new package should close the corresponding ITP bug for that package.
283 This warning can be ignored if the package is not intended for Debian or
284 if it is a split of an existing Debian package.
287 Tag: debian-changelog-line-too-long
290 Info: The given line of the latest changelog entry is over 80 columns.
291 Such changelog entries may look poor in terminal windows and mail
292 messages and be annoying to read. Please wrap changelog entries at 80
293 columns or less where possible.
295 Tag: changelog-news-debian-mismatch
298 Info: The latest entries in the Debian changelog file and NEWS.Debian file
299 are for the same version but the given field doesn't match. The
300 changelog information is canonical and the NEWS.Debian information is
301 ignored, but it may be confusing to users to have them be different.
303 Tag: version-refers-to-distribution
306 Info: The Debian portion of the package version contains a reference to a
307 particular Debian release or distribution. This should only be done for
308 uploads targeted at a particular release, not at unstable or
309 experimental, and should refer to the release by version number or code
312 Using "testing" or "stable" in a package version targeted at the current
313 testing or stable release is less informative than using the code name or
314 version number and may cause annoying version sequencing issues if the
315 package doesn't change before the next release cycle starts.