vcs.maemo.org Git - maemian/blob - nokia-lintian/checks/debconf.desc

   1 Check-Script: debconf
   2 Author: Colin Watson <cjw44@flatline.org.uk>
   3 Abbrev: dc
   4 Type: binary, udeb, source
   5 Unpack-Level: 2
   6 Info: This looks for common mistakes in packages using debconf.
   7 Needs-Info: scripts
   8
   9 Tag: missing-debconf-dependency
  10 Type: warning
  11 Info: Packages using debconf should depend on it, since debconf is not an
  12  essential package.
  13
  14 Tag: missing-debconf-dependency-for-preinst
  15 Type: warning
  16 Info: Packages using debconf in their preinst script must pre-depend
  17  on debconf, with appropriate discussion on &debdev;.  Since debconf is
  18  almost always already installed, this is normally better than depending
  19  on it and falling back to a different configuration system.
  20
  21 Tag: duplicate-fields-in-templates
  22 Type: error
  23 Info: A template contains two identical fields (with identical values or
  24  not). This is either an error in this template, or two templates are
  25  not properly separated by a lone newline.
  26
  27 Tag: unknown-field-in-templates
  28 Type: error
  29 Info: See the Debconf Programmer's Tutorial for a list of the possible
  30  fields in a debconf templates file.
  31
  32 Tag: no-template-name
  33 Type: error
  34 Info: The templates file contains a template without a `Template:' field.
  35
  36 Tag: malformed-template-name
  37 Type: error
  38 Info: The `Template:' field should contain more than one component, each
  39  separated by a slash (`/'). Each component may only consist of the
  40  alphanumeric characters, `+', `-', and `.'.
  41
  42 Tag: no-template-type
  43 Type: error
  44 Info: The templates file contains a template without a `Type:' field.
  45
  46 Tag: unknown-template-type
  47 Type: error
  48 Info: A `Type:' field in a templates file provided by this package uses an
  49  unknown data type. Valid types are currently `string', `boolean', `select',
  50  `multiselect', `note', `text', and `password'.
  51
  52 Tag: empty-translated-choices
  53 Type: error
  54 Info: When the translation of a Choices: field is empty, the whole question
  55  is skipped (and nothing is selected). Please verify that the translation
  56  you're using is valid.
  57
  58 Tag: mismatch-translated-choices
  59 Type: error
  60 Info: A `Choices:' field is a comma separated list, and translated
  61  `Choices:' fields must have the exact same number of elements.  One
  62  of the translations does not follow this rule, you should contact the
  63  translator and request for a new translation where elements of `Choices:'
  64  fields have no embedded commas.
  65  .
  66  Cdebconf understands escaped commas in such fields, but packages
  67  outside the scope of debian-installer must not have them until they are
  68  also supported by debconf.
  69
  70 Tag: select-without-choices
  71 Type: error
  72 Info: Templates using the `select' or `multiselect' data types must provide
  73  a `Choices:' field listing the possible values of the template.
  74
  75 Tag: boolean-template-has-bogus-default
  76 Type: error
  77 Info: The `boolean' type in a debconf template, can have only two values: true
  78  and false. The default has been set to something different.
  79
  80 Tag: no-template-description
  81 Type: error
  82 Info: The templates file contains a template without a `Description:' field.
  83
  84 Tag: duplicate-long-description-in-template
  85 Type: warning
  86 Info: The long description of one of the templates provided by this package
  87  is a duplicate of the short description. If you cannot provide a good
  88  extended description, it is better to leave it blank.
  89
  90 Tag: config-does-not-load-confmodule
  91 Type: warning
  92 Info: The config script must load one of the debconf libraries.
  93
  94 Tag: postinst-uses-db-input
  95 Type: warning
  96 Info: It is generally not a good idea for postinst scripts to use debconf
  97  commands like <tt>db_input</tt>. Typically, they should restrict themselves
  98  to <tt>db_get</tt> to request previously acquired information, and have the
  99  config script do the actual prompting.
 100
 101 Tag: postinst-does-not-load-confmodule
 102 Type: warning
 103 Info: Even if your postinst does not involve debconf, you currently need to
 104  make sure it loads one of the debconf libraries. This will be changed in
 105  the future.
 106
 107 Tag: loads-obsolete-confmodule
 108 Type: warning
 109 Info: The maintainer script uses an obsolete name for a debconf confmodule.
 110  Shell scripts should source <tt>/usr/share/debconf/confmodule</tt>, while
 111  Perl scripts should use <tt>Debconf::Client::ConfModule</tt>.
 112
 113 Tag: postrm-does-not-purge-debconf
 114 Type: warning
 115 Info: Packages using debconf should call <tt>db_purge</tt> or its equivalent
 116  in their postrm. If the package uses debhelper, dh_installdebconf(1) should
 117  take care of this.
 118
 119 Tag: isdefault-flag-is-deprecated
 120 Type: warning
 121 Info: The 'isdefault' flag on debconf questions is deprecated as of debconf
 122  0.5.00, and has been replaced by 'seen' with the inverse meaning. From
 123  debconf 0.5 onwards there should be very few reasons to use isdefault/seen
 124  anyway, as backing up works much better now. See
 125  /usr/share/doc/debconf-doc/changelog.gz for more information.
 126  .
 127  The misuse of isdefault often leads to questions being asked twice in one
 128  installation run, or, worse, on every upgrade. Please test your package
 129  carefully to make sure this does not happen.
 130
 131 Tag: debconf-config-not-executable
 132 Type: error
 133 Info: The debconf `config' script in the package control area must be
 134  executable.
 135
 136 Tag: no-debconf-config
 137 Type: warning
 138 Info: The package contains a `templates' file in its control area but has no
 139  corresponding `config' script. This is occasionally OK, but is usually an
 140  error.
 141
 142 Tag: no-debconf-templates
 143 Type: warning
 144 Info: The package contains a `config' script in its control area but has no
 145  corresponding `templates' file. This is occasionally OK, but is usually an
 146  error.
 147
 148 Tag: debconf-is-not-a-registry
 149 Type: warning
 150 Info: In the Unix tradition, Debian packages should have human-readable and
 151  human-editable configuration files. This package uses debconf commands
 152  outside its maintainer scripts, which often indicates that it is taking
 153  configuration information directly from the debconf database. Typically,
 154  packages should use debconf-supplied information to generate configuration
 155  files, and - to avoid losing configuration information on upgrades - should
 156  parse these configuration files in the `config' script if it is necessary
 157  to ask the user for changes.
 158  .
 159  Some standalone programs may legitimately use debconf to prompt the user
 160  for questions. If you maintain a package containing such a program, please
 161  install an override. Other exceptions to this check include configuration
 162  scripts called from the package's post-installation script.
 163
 164 Tag: debconf-error-requires-versioned-depends
 165 Type: info
 166 Info: Debconf only supports the error template type as of version 1.4.69.
 167  Packages that use this template type should declare a dependency on that
 168  version of debconf.
 169  .
 170  Since error types were added after debconf-2.0, one cannot use the normal
 171  debconf-2.0 alternative to allow for cdebconf or other implementations.
 172  Instead, use <tt>debconf (&gt;= 1.4.69) | cdebconf (&gt;= 0.39)</tt>.
 173  .
 174  All versions of debconf back to etch support error templates, but the
 175  debconf released with sarge didn't, so this dependency is still helpful
 176  for oldstable backports.
 177
 178 Tag: malformed-prompt-in-templates
 179 Type: warning
 180 Info: The short description of a select, multiselect, string and password
 181  debconf template is a prompt and not a title. Avoid question style
 182  prompts ("IP Address?") in favour of "opened" prompts ("IP address:").
 183  The use of colons is recommended.
 184  .
 185  If this template is only used internally by the package and not displayed
 186  to the user, put "for internal use" in the short description.
 187 Ref: devref 6.5.4.2
 188
 189 Tag: malformed-title-in-templates
 190 Type: warning
 191 Info: The short description of a note debconf template should be written
 192  as a title and therefore should not end with a period, question mark,
 193  colon, or semicolon.
 194 Ref: devref 6.5.4.2.4
 195
 196 Tag: malformed-question-in-templates
 197 Type: warning
 198 Info: The short description of a boolean debconf template should be
 199  phrased in the form of a question which should be kept short and should
 200  generally end with a question mark. Terse writing style is permitted and
 201  even encouraged if the question is rather long.
 202  .
 203  If this template is only used internally by the package and not displayed
 204  to the user, put "for internal use" in the short description.
 205 Ref: devref 6.5.4.2.2
 206
 207 Tag: using-question-in-extended-description-in-templates
 208 Type: warning
 209 Info: The extended description of a debconf template should never include
 210  a question.
 211  .
 212  If this template is only used internally by the package and not displayed
 213  to the user, put "for internal use" in the short description.
 214 Ref: devref 6.5.3.2
 215
 216 Tag: using-imperative-form-in-templates
 217 Type: warning
 218 Info: Do not use useless imperative constructions such as "Please choose...",
 219  "Enter...". The interface will make it obvious that the user needs to
 220  choose or enter something.
 221 Ref: devref 6.5.4.2
 222
 223 Tag: using-first-person-in-templates
 224 Type: warning
 225 Info: You should avoid the use of first person ("I will do this..." or
 226  "We recommend..."). The computer is not a person and the Debconf
 227  templates do not speak for the Debian developers. You should use neutral
 228  construction and often the passive form.
 229  .
 230  If this template is only used internally by the package and not displayed
 231  to the user, put "for internal use" in the short description.
 232 Ref: devref 6.5.2.5
 233
 234 Tag: making-assumptions-about-interfaces-in-templates
 235 Type: warning
 236 Info: Template text should not make reference to widgets belonging to
 237  some debconf interfaces. Sentences like "If you answer Yes..." have no
 238  meaning for users of graphical interfaces which use checkboxes for
 239  boolean questions.
 240 Ref: devref 6.5.2.4
 241
 242 Tag: too-long-short-description-in-templates
 243 Type: warning
 244 Info: The short description should be kept short (50 characters or so) so
 245  that it may be accomodated by most debconf interfaces. Keeping it short
 246  also helps translators, as usually translations tend to end up being
 247  longer than the original.
 248 Ref: devref 6.5.3.2
 249
 250 Tag: too-long-extended-description-in-templates
 251 Type: warning
 252 Info: Some debconf interfaces cannot deal very well with descriptions of
 253  more than about 20 lines, so try to keep the extended description below
 254  this limit.
 255 Ref: devref 6.5.3.2
 256
 257 Tag: unknown-debconf-priority
 258 Type: error
 259 Info: The given maintainer script calls db_input or or db_text with a
 260  first argument that doesn't match one of the known priorities.  The
 261  supported priorities are low, medium, high, and critical.
 262 Ref: debconf-devel(7)
 263
 264 Tag: possible-debconf-note-abuse
 265 Type: warning
 266 Info: Debconf notes should be used only for important notes that the
 267  user really should see, since debconf will go to great pains to make
 268  sure the user sees it.
 269  .
 270  Displaying a note with a low priority is conflicting with this statement,
 271  since using a low or medium priority shows that the note is not
 272  important.
 273  .
 274  The right fix is NOT to increase the priority of the note, but to move
 275  it somewhere else in the inline documentation, for example in a
 276  README.Debian file for notes about package usability or NEWS.Debian for
 277  changes in the package behavior, or to simply drop it if it is not
 278  needed (e.g. "welcome" notes). Changing the templates type to "error"
 279  can also be appropriate, such as for input validation errors.
 280 Ref: policy 3.9.1
 281
 282 Tag: select-with-boolean-choices
 283 Type: warning
 284 Info: Select templates with only yes and no choices should use the boolean
 285  type instead.
 286 Ref: debconf-devel(7)
 287
 288 Tag: template-uses-unsplit-choices
 289 Type: warning
 290 Experimental: yes
 291 Info: The use of _Choices in templates is deprecated.
 292  An _Choices field must be translated as a single string.
 293  .
 294  Using __Choices allows each choice to be translated separately, easing
 295  translation and is therefore recommended.
 296  .
 297  Instead of simply replacing all occurrences of "_Choices" by "__Choices",
 298  apply the method described in po-debconf(7) under "SPLITTING CHOICES
 299  LIST", to avoid breaking existing translations.
 300  .
 301  If in doubt, please ask for help on the debian-i18n mailing list.
 302 Ref: po-debconf(7)
 303
 304 Tag: unused-debconf-template
 305 Type: info
 306 Info: Templates which are not used by the package should be removed from
 307  the templates file.
 308  .
 309  This will reduce the size of the templates database and prevent
 310  translators from unnecessarily translating the template's text.
 311  .
 312  In some cases, the template is used but lintian is unable to determine
 313  this.  Common causes are:
 314  .
 315  - the maintainer scripts embed a variable in to the template name in
 316  order to allow a template to be selected from a range of similar
 317  templates (e.g. 'db_input low start_$service_at_boot')
 318  .
 319  - the template is not used by the maintainer scripts but is used by
 320  a program in the package
 321  .
 322  - the maintainer scripts are written in perl.  lintian currently only
 323  understands the shell script debconf functions.
 324  .
 325  If any of the above applies, please install an override.