~ubuntu-branches/ubuntu/vivid/debian-policy/vivid-proposed

[ Colin Watson ]
* Fix path to changelog.Debian.gz in footnote on documentation symlinks.

[ Bill Allombert ]
* Convert upgrading-checklist to debiandoc-sgml. This generates a better
 looking .txt file.
 Closes: #567845
* Fix typo in package_upstream-version.orig.tar.gz.
 Thanks, Salvatore Bonaccorso. (Closes: #558430)
* Replace 'copyright and distribution license' by 'copyright information
 and distribution license' (three times).
 Proposed by Jonathan Nieder.
 Seconded: Steve Langasek <vorlon@debian.org>
 Seconded: Thijs Kinkhorst <thijs@debian.org>
 Seconded: Julien Cristau <jcristau@debian.org>
 Seconded: Gregor Herrmann <gregoa@debian.org>
 Closes: #566220
* extend UID range of user accounts by removing the 30000-59999 reserved
 ranges.
 Proposed by Santiago Vila
 Seconded: Russ Allbery <rra@debian.org>
 Seconded: Luk Claes <luk@debian.org>
 Seconded: Raphael Hertzog <hertzog@debian.org>
 Seconded: Steve Langasek <vorlon@debian.org>
 Closes: #582495

[ Russ Allbery ]
* Policy: Overhaul Breaks, Conflicts, Provides, and Replaces
 Wording: Russ Allbery <rra@debian.org>
 Seconded: Steve Langasek <vorlon@debian.org>
 Seconded: Raphael Hertzog <hertzog@debian.org>
 Closes: #578854
* Policy: Support for architecture wildcards
 Wording: Manoj Srivastava <srivasta@debian.org>
 Wording: Russ Allbery <rra@debian.org>
 Seconded: Guillem Jover <guillem@debian.org>
 Seconded: Andrew McMillan <andrew@morphoss.com>
 Seconded: Steve Langasek <vorlon@debian.org>
 Closes: #530687
* Policy: Except init.d scripts from the normal set -e requirement
 Wording: Russ Allbery <rra@debian.org>
 Seconded: Raphael Hertzog <hertzog@debian.org>
 Seconded: Guillem Jover <guillem@debian.org>
 Closes: #562506
* Policy: Maintainer scripts might not have a controlling terminal
 Wording: Russ Allbery <rra@debian.org>
 Seconded: Guillem Jover <guillem@debian.org>
 Seconded: Andrew McMillan <andrew@morphoss.com>
 Seconded: Steve Langasek <vorlon@debian.org>
 Closes: #224509
* Policy: Fully specify the date format for changelog entries
 Wording: Charles Plessy <plessy@debian.org>
 Seconded: Russ Allbery <rra@debian.org>
 Seconded: Andrew McMillan <andrew@morphoss.com>
 Seconded: Giacomo A. Catenazzi <cate@debian.org>
 Closes: #569174
* Policy: Deprecate /usr/share/common-licenses/BSD
 Wording: Russ Allbery <rra@debian.org>
 Seconded: Emilio Pozuelo Monfort <pochu@debian.org>
 Seconded: Jakub Wilk <jwilk@debian.org>
 Seconded: gregor herrmann <gregoa@debian.org>
 Closes: #284340
* Policy: Document Checksums-Sha1 and Checksums-Sha256
 Wording: Russ Allbery <rra@stanford.edu>
 Seconded: Julien Cristau <jcristau@debian.org>
 Seconded: Emilio Pozuelo Monfort <pochu@debian.org>
 Closes: #478295
* Policy: Prohibit duplicate field names in a control paragraph
 Wording: Russ Allbery <rra@debian.org>
 Seconded: Charles Plessy <plessy@debian.org>
 Seconded: Steve Langasek <vorlon@debian.org>
 Seconded: Emilio Pozuelo Monfort <pochu@debian.org>
 Closes: #555978
* Policy: Relax requirement that library dev files be in one package
 Wording: Russ Allbery <rra@debian.org>
 Seconded: Julien Cristau <jcristau@debian.org>
 Seconded: Andrew McMillan <andrew@morphoss.com>
 Closes: #347581
* Policy: Tighten requirements for maintainer-like fields
 Wording: Russ Allbery <rra@debian.org>
 Seconded: Emilio Pozuelo Monfort <pochu@debian.org>
 Seconded: Andrew McMillan <andrew@morphoss.com>
 Closes: #575639
* Policy: Update Format control field documentation
 Wording: Russ Allbery <rra@debian.org>
 Wording: Charles Plessy <plessy@debian.org>
 Seconded: Charles Plessy <plessy@debian.org>
 Seconded: Emilio Pozuelo Monfort <pochu27@gmail.com>
 Closes: #547272
* Debconf: Add SETTITLE, like title but uses a template
 Wording: Frans Pop <elendil@planet.nl>
 Seconded: Russ Allbery <rra@debian.org>
 Seconded: Ben Pfaff <blp@cs.stanford.edu>
 Closes: #560411
* Perl Policy: Change perlapi provides to use an ABI version
 Wording: Niko Tyni <ntyni@debian.org>
 Seconded: Russ Allbery <rra@debian.org>
 Seconded: Brendan O'Dea <bod@debian.org>
 Seconded: Damyan Ivanov <dmn@debian.org>
 Closes: #579457
* Perl Policy: Recommend DESTDIR instead of PREFIX with Makefile.PL
 Wording: Niko Tyni <ntyni@debian.org>
 Seconded: Russ Allbery <rra@debian.org>
 Seconded: Raphael Hertzog <hertzog@debian.org>
 Closes: #579461
* Standardize dpkg state wording and bring it in line with dpkg,
 renaming Failed-Config to Half-Configured and use uniform
 capitalization and punctuation. (Closes: #442134)
* Remove documentation of alternative changelog formats. This feature
 is not allowed in the Debian archive and will be documented in the
 dpkg-dev documentation instead. The documentation that was in Policy
 was also somewhat outdated. (Closes: #555009, see #584141)
* Remove obsolete footnote sentence saying that dpkg-statoverride is a
 new feature and not well-known. (Closes: #563425)
* Clarify in the Perl Policy that perl-base is essential, not perl, and
 don't imply packages need to depend on perl-base. (Closes: #576594)
* Document the special debian-installer section in the list of current
 sections and add a link to the list of sections in unstable, which
 contains longer descriptions. (Closes: #577666)
* Remove the footnote listing every architecture known to dpkg. This
 list can be trivially produced by dpkg-architecture -L (already
 noted), is very long, and quickly becomes out-of-date.
* Move silly version ordering example to a footnote. (Closes: #560839)
* Reletter the process steps to not skip State C and use more
 traditional foreground and background colors for Process.html and
 README.html. (Closes: #584521)
* Fix typo in footnote about help2man. (Closes: #584796)
* Add an example for Replaces when a package is split. Thanks, Uwe
 Kleine-König. (Closes: #572253)
* Explicitly state that packages may remove unmodified, obsolete
 configuration files during upgrade. (Closes: #470633)
* Clarify the wording around which build dependencies must be satisfied
 for different debian/rules targets and add a footnote to the
 description of the build-arch and build-indep targets explaining why
 this split does not currently work as desired. (Closes: #328951)
* Avoid "Debianised" or "Debianized" in favor of just "Debian" or
 "Debian package" as appropriate. Patch from Ben Finney.
 (Closes: #586163)
* Switch to source format 3.0 (native).

files added:
debian/source

debian/source/format

tools

tools/license-count

upgrading-checklist.sgml

files removed:
upgrading-checklist.html

upgrading-checklist.org

upgrading-checklist.txt

files modified:
.gitignore

Makefile

Process.html

Process.org

Process.txt

README-css.el

README.html

README.txt

debconf_spec/debconf_specification.xml

debconf_spec/include/commands.xml

debconf_spec/include/types.xml

debian/changelog

debian/control

debian/rules

perl-policy.sgml

policy.sgml

Show diffs side-by-side

added added

removed removed

upgrading-checklist.sgml

<!doctype debiandoc system>

<book>

<title> Policy checklist for upgrading your packages </title>

<author> Bill Allombert <email/ballombe@debian.org/ </author>

<author> Josip Rodin </author>

<author> Julian Gilbey </author>

<author> Russ Allbery </author>

<author> Manoj Srivastava <email/srivasta@debian.org/

<chapt> About the checklist

The checklist below has been created to simplify the upgrading process

of old packages. Note that this list is not "official"; it simply

gives an indication of what has changed and whether you are likely to

need to make changes to your package in light of this. If you have

doubts about a certain topic, if you need more details, or if you

think some other package does not comply with policy, please refer to

the Policy Manual itself. All of the changes from version 3.0.0

onwards indicate which section of the Policy Manual discusses the

issue: [3.4] means section 3.4. The section numbering changed when

the packaging manual was incorporated into policy; the section numbers

used below refer to the current version.

Here is how the check list works: Check which policy version your

package was checked against last (indicated in the "Standards-Version"

field of the source package). Then move upwards until the top and

check which of the items on the list might concern your package. Note

which sections of policy discuss this, and then check out the Policy

Manual for details. If you are upgrading from Policy version < 2.5.0,

it may be easier to check through the whole of policy instead of

picking your way through this list.

<chapt> The checklist

<sect> Version 3.9.0.0

Release Jun 2010.

<item>The required format for the date in a changelog entry and in the

Date control field is now precisely specified.

</item>

<item>A control paragraph must not contain more than one instance of a

particular field name.

</item>

<item>Document and recommend the <tt>Checksums-Sha1</tt>

and <tt>Checksums-Sha256</tt> fields in <file>*.dsc</file>

and <file>*.changes</file> files.

</item>

<item>The <tt>Format</tt> field of <file>.changes</file> files is now

1.8. The <tt>Format</tt> field syntax for source

package <file>.dsc</file> files allows a subtype in parentheses, and it

is used for a different purpose than the <tt>Format</tt> field

for <file>.changes</file> files.

</item>

<item>The syntax of the <tt>Maintainer</tt> field is now must rather

than should.

</item>

<item>The comma separating entries in <tt>Uploaders</tt> is now must

rather than should.

</item>

<item>Architecture wildcards may be used in addition to specific

architectures in <file>debian/control</file> and <file>*.dsc</file>

Architecture fields, and in architecture restrictions in build

relationships.

</item>

<item>Maintainer scripts are no longer guaranteed to run with a

controlling terminal and must be able to fall back to noninteractive

behavior (debconf handles this). Maintainer scripts may abort if there

is no controlling terminal and no reasonable default for a high-priority

question, but should avoid this if possible.

</item>

<item><tt>Breaks</tt> should be used with <tt>Replaces</tt> for moving

files between packages.

</item>

<item><tt>Breaks</tt> should normally be used instead

of <tt>Conflicts</tt> for transient issues and moving files between

packages. New documentation of when each should be used.

</item>

<item>Use <tt>Conflicts</tt> with <tt>Provides</tt> if only one provider

of a virtual facility can ge installed at a time.

</item>

<item>All shared library development files are no longer required to be

in the <tt>-dev</tt> package, only be available when the <tt>-dev</tt>

100

package is installed. This allows the <tt>-dev</tt> package to be split

101

as long as it depends on the additional packages.

102

</item>

103

104

<item>The UID range of user accounts is extended to 1000-59999.

105

</item>

106

107

<item><file>init.d</file> scripts are a possible exception from the

108

normal requirement to use <tt>set -e</tt> in each shell script.

109

</item>

110

111

<item>The UCB BSD license was removed from the list of licenses that

112

should be referenced from <file>/usr/share/common-licenses/BSD</file>.

113

It should instead be included directly

114

in <file>debian/copyright</file>, although it will still be in

115

common-licenses for the time being.

116

</item>

117

<tag>debconf</tag>

118

<item>Add <tt>SETTITLE</tt> (which has been supported for some time).

119

Like <tt>TITLE</tt> but takes a template instead of a string to allow

120

translation.

121

</item>

122

123

<item><package>perl-base</package> now

124

provides <package>perlapi-<var>abiname</var></package> instead of a

125

package based solely on the Perl version. Perl packages must now depend

126

on <package>perlapi-$Config{debian_abi}</package>, falling back

127

on <tt>$Config{version}</tt> if <tt>$Config{debian_abi}</tt> is not set.

128

</item>

129

130

<item>Packages using <file>Makefile.PL</file> should use

131

<tt>DESTDIR</tt> rather than <tt>PREFIX</tt> to install into the package

132

staging area. <tt>PREFIX</tt> only worked due to a Debian-local patch.

133

</item>

134

</taglist>

135

136

<sect> Version 3.8.4.0

137

138

139

Release Jan 2010.

140

141

142

143

<item> An FHS exception has been granted for multiarch libraries.

144

Permitting files to instead be installed to <file>/lib/triplet</file> and

145

<file>/usr/lib/triplet</file> directories.

146

</item>

147

148

<item>Explicitly state that packages may not contain named pipes and

149

should instead create them in postinst and remove them in prerm or postrm.

150

</item>

151

152

<item><file>/sys</file> and <file>/selinux</file> directories are explicitly

153

allowed as an exception to the FHS.

154

</item>

155

</taglist>

156

157

<sect> Version 3.8.3.0

158

159

Released Aug 2009.

160

161

162

163

<item>Add DEB_*_ARCH_CPU and DEB_*_ARCH_OS variables and

164

recommend them over GNU-style variables for that information.

165

</item>

166

167

<item>Source package Architecture fields may contain <em/all/ in

168

combination with other architectures. Clarify when <em/all/ and <em/any/

169

may be used in different versions of the field.

170

</item>

171

172

<item>The Debian archive software does not support uploading

173

to multiple distributions with one <file>*.changes</file> file.

174

</item>

175

176

<item>The Binary field may span multiple lines.

177

</item>

178

179

<item>Remove the permission for shared library packages to

180

install libraries in a non-standard location and modify <file/ld.so.conf/.

181

Packages should either be installed in a standard library directory

182

or packages using them should be built with RPATH.

183

</item>

184

185

<item>Clarify installation directories for X programs and

186

remove the requirement to pre-depend on x11-common before installing

187

into <file>/usr/include/X11</file> and <file>/usr/lib/X11</file>.

188

</item>

189

190

<item>Remove the requirement that all characters in a manual

191

page be representable in the legacy encoding for that language.

192

</item>

193

194

<item>Localized man pages should either be kept up-to-date with

195

the original version or warn that they're not up-to-date, either

196

with warning text or by showing missing or changed portions in the

197

original language.

198

</item>

199

200

<item>install-info is now handled via triggers so packages no

201

longer need to invoke it in maintainer scripts. Info documents

202

should now have directory sections and entries in the document.

203

Packages containing info documents should add a dependency to

204

support partial upgrades.

205

</item>

206

207

<item>The requirement for Perl modules to have a versioned

208

Depend and Build-Depend on <tt>perl >= 5.6.0-16</tt> has been removed.

209

</item>

210

</taglist>

211

212

<sect> Version 3.8.2.0

213

214

215

Released Jun 2009.

216

217

218

219

<item>The list of archive sections has been significantly expanded. See

220

<url id="http://lists.debian.org/debian-devel-announce/2009/03/msg00010.html"

221

name="this debian-devel-announce message">

222

for the list of new sections and rules for how to categorize

223

packages.

224

</item>

225

226

<item>All packages must use debconf or equivalent for user prompting,

227

though essential packages or their dependencies may also fall

228

back on other methods.

229

</item>

230

231

<item>The requirements for source package names are now explicitly

232

spelled out.

233

</item>

234

235

<item>Legacy XFree86 servers no longer get a special exception from the

236

FHS permitting <file>/etc/X11/XF86Config-4</file>.

237

</item>

238

239

<item>Removed obsolete dependency requirements for packages that use

240

<file>/var/mail</file>.

241

</item>

242

243

<item>Speedo fonts are now deprecated. The X backend was disabled

244

starting in lenny.

245

</item>

246

247

<item>The GNU Free Documentation License version 1.3 is included in

248

common-licenses and should be referenced from there.

249

</item>

250

</taglist>

251

252

<sect> Version 3.8.1.0

253

254

255

Released Mar 2009.

256

257

258

259

<item>Care should be taken when adding functionality to essential and

260

such additions create an obligation to support that functionality

261

in essential forever unless significant work is done.

262

</item>

263

264

<item>Changelog files must be encoded in UTF-8.

265

</item>

266

267

<item>Tighten some format requirements for changelog files from a should

268

to a must.

269

</item>

270

271

<item>Remove alternative changelog formats. Debian only supports one

272

changelog format for the Debian Archive.

273

</item>

274

275

<item>New nocheck option for DEB_BUILD_OPTIONS indicating any build-time

276

test suite provided by the package should not be run.

277

</item>

278

279

<item>All control files must be encoded in UTF-8.

280

</item>

281

282

<item>debian/control allows comment lines starting with # with no

283

preceding whitespace.

284

</item>

285

286

<item>Init scripts ending in .sh are not handled specially. They are not

287

sourced and are not guaranteed to be run by <prgn>/bin/sh</prgn> regardless

288

of the #! line. This brings Policy in line with the long-standing

289

behavior of the init system in Debian.

290

</item>

291

292

<item>The start action of an init script must exit successfully and not

293

start the daemon again if it's already running.

294

</item>

295

296

<item><file>/var/run</file> and <file>/var/lock</file> may be mounted as

297

temporary filesystems, and init scripts must therefore create any necessary

298

subdirectories dynamically.

299

</item>

300

301

<item> <file>/bin/sh</file> scripts may assume that local can take multiple

302

variable arguments and supports assignment.

303

</item>

304

305

<item>User mailboxes may be mode 600 and owned by the user rather than

306

mode 660, owned by user, and group mail.

307

</item>

308

</taglist>

309

310

<sect> Version 3.8.0.0

311

312

313

Released Jun 2008.

314

315

316

317

<item>The base section has been removed. contrib and non-free have been

318

removed from the section list; they are only categories. The base

319

system is now defined by priority.

320

321

<item>If <prgn>dpkg-source -x</prgn> doesn't provide the source that will be

322

compiled, a debian/rules patch target is recommended and should do whatever

323

else is necessary.

324

325

<item>Standardized the format of DEB_BUILD_OPTIONS. Specified permitted

326

characters for tags, required that tags be whitespace-separated,

327

allowed packages to assume non-conflicting tags, and required

328

unknown flags be ignored.

329

330

<item>Added parallel=n to the standardized DEB_BUILD_OPTIONS tags,

331

indicating that a package should be built using up to n parallel

332

processes if the package supports it

333

334

<item>Debian packages should not use convenience copies of code from other

335

packages unless the included package is explicitly intended to be

336

used that way.

337

338

<item>If dpkg-source -x doesn't produce source ready for editing and

339

building with dpkg-buildpackage, packages should include a

340

<file>debian/README.source</file> file explaining how to generate

341

the patched source, add a new modification, and remove an existing

342

modification. This file may also be used to document packaging a

343

new upstream release and any other complexity of the Debian build

344

process.

345

346

<item>The Uploaders field in debian/control may be wrapped.

347

348

<item>An empty Debian revision is equivalent to a Debian revision of 0 in

349

a version number.

350

351

<item>New Homepage field for upstream web sites.

352

353

<item>The Breaks field declares that this package breaks another and

354

prevents installation of the breaking package unless the package

355

named in Breaks is deconfigured first. This field should not be

356

used until the dpkg in Debian stable supports it.

357

358

<item>Clarify which files should go into a shared library package, into a

359

separate package, or into the -dev package. Suggest -tools instead

360

of -runtime for runtime support programs, since that naming is more

361

common in Debian.

362

363

<item>Files in <file>/etc/cron.{hourly,daily,weekly,monthly}</file> must be

364

configuration files (upgraded from should). Mention the hourly

365

directory.

366

367

<item>Packages providing <file>/etc/X11/Xresources</file> files need not

368

conflict with <tt> xbase (<< 3.3.2.3a-2)</tt>, which is

369

long-obsolete.

370

371

<item>Manual pages in locale-specific directories should use either the

372

legacy encoding for that directory or UTF-8. Country names should

373

not be included in locale-specific manual page directories unless

374

indicating a significant difference in the language. All

375

characters in the manual page source should be representable in the

376

legacy encoding for a locale even if the man page is encoded in

377

UTF-8.

378

379

<item>The Apache 2.0 license is now in common-licenses and should be

380

referenced rather than quoted in <file>debian/copyright</file>.

381

382

<item>Packages in contrib and non-free should state in the copyright file

383

that the package is not part of Debian GNU/Linux and briefly

384

explain why.

385

<tag>debconf</tag>

386

<item>Underscore (_) is allowed in debconf template names.

387

</taglist>

388

389

<sect> Version 3.7.3.0

390

391

392

Released Dec 2007.

393

394

395

396

<item>Package version numbers may contain tildes, which sort before

397

anything, even the end of a part.

398

399

<item>Scripts may assume that <file>/bin/sh</file> supports local (at a basic

400

level) and that its test builtin (if any) supports -a and -o binary

401

logical operators.

402

403

<item>The substitution variable ${binary:Version} should be used in place

404

of ${Source-Version} for dependencies between packages of the same

405

library.

406

<tag>menu policy</tag>

407

<item>Substantial reorganization and renaming of sections in the Debian

408

menu structure. Packages with menu entries should be reviewed to

409

see if the menu section has been renamed or if one of the new

410

sections would be more appropriate.

411

412

<item>The Source field in a .changes file may contain a version number

413

in parentheses.

414

415

<item>The acceptable values for the Urgency field are low, medium, high,

416

critical, or emergency.

417

418

<item>The shlibs file now allows an optional type field, indicating the

419

type of package for which the line is valid. The only currently

420

supported type is udeb, used with packages for the Debian

421

Installer.

422

423

<item>Packages following the Debian Configuration management

424

specification must allow for translation of their messages by using

425

a gettext-based system such as po-debconf.

426

427

<item>GFDL 1.2, GPL 3, and LGPL 3 are now in common-licenses and should

428

be referenced rather than quoted in debian/copyright.

429

</taglist>

430

431

<sect> Version 3.7.2.2

432

433

434

Released Oct 2006.

435

436

437

<tag>6.1</tag> <item>Maintainer scripts must not be world writeable (up from a

438

should to a must)</item>

439

</taglist>

440

441

<sect> Version 3.7.2.0

442

443

444

Released Apr 2006.

445

446

447

<tag>11.5</tag> <item>Revert the cgi-lib change. </item>

448

</taglist>

449

450

<sect> Version 3.7.1.0

451

452

453

Released Apr 2006.

454

455

456

457

<item>It is now possible to create shared libraries without

458

relocatable code (using -fPIC) in certain exceptional cases,

459

provided some procedures are followed, and for creating static

460

libraries with relocatable code (again, using -fPIC).

461

Discussion on debian-devel@lists.debian.org, getting a rough

462

consensus, and documenting it in README.Debian constitute most

463

of the process.

464

465

<item>Packages should install any relevant files into the directories

466

<file>/usr/include/X11/</file> and <file>/usr/lib/X11/</file>, but if

467

they do so, they must pre-depend on <tt>x11-common (>= 1:7.0.0)</tt>

468

</taglist>

469

470

<sect> Version 3.7.0.0

471

472

473

Released Apr 2006.

474

475

476

477

<item>Packages shipping web server CGI files are expected to install

478

them in <file>/usr/lib/cgi-lib/</file> directories. This location change

479

perhaps should be documented in NEWS

480

481

<item>Web server packages should include a standard scriptAlias of

482

cgi-lib to <file>/usr/lib/cgi-lib</file>.

483

484

<item>The version of FHS mandated by policy has been upped to

485

2.3. There should be no changes required for most packages,

486

though new top level directories <file>/media</file>, <file>/srv</file>,

487

etc. may be of interest.

488

489

<item>All fields, apart from the Uploaders field, in the control file

490

are supposed to be a single logical line, which may be spread

491

over multiple physical lines (newline followed by space is

492

elided). However, any parser for the control file must allow

493

the Uploaders field to be spread over multiple physical lines

494

as well, to prepare for future changes.

495

496

<item>When scripts are installed into a directory in the system

497

PATH, the script name should not include an extension that

498

denotes the scripting language currently used to implement it.

499

500

501

<item>packages that invoke initscripts now must use invoke-rc.d to do

502

so since it also pays attention to run levels and other local

503

constraints.

504

505

<item>We no longer use <file>/usr/X11R6</file>, since we have

506

migrated away to using Xorg paths. This means, for one thing, fonts

507

live in <file>/usr/share/fonts/X11/</file> now, and <file>/usr/X11R6</file>

508

is gone.

509

</taglist>

510

511

<sect> Version 3.6.2.0

512

513

514

Released 2005

515

516

517

518

<item>Recommend. doc-base, and not menu, for registering package documentation.

519

</item>

520

521

<item>Run time support programs should live in subdirectories of

522

<file>/usr/lib/</file> or <file>/usr/share</file>, and preferably the shared

523

lib is named the same as the package name (to avoid name collisions).

524

</item>

525

526

<item>It is recommended that HTTP servers provide an alias /images to

527

allow packages to share image files with the web server

528

</item>

529

</taglist>

530

531

<sect> Version 3.6.1.0

532

533

534

Released Aug 2003.

535

536

537

538

<item>Prompting the user should be done using debconf. Non debconf

539

user prompts are now deprecated.

540

</taglist>

541

542

<sect> Version 3.6.0

543

544

545

Released Jul 2003.

546

547

548

549

<item>Restructuring causing shifts in section numbers and bumping of

550

the minor version number:

551

552

<item>Many packaging manual appendices that were integrated into policy

553

sections are now empty, and replaced with links to the Policy.

554

In particular, the appendices that included the list of control

555

fields were updated (new fields like Closes, Changed-By were added)

556

and the list of fields for each of control, .changes and .dsc files

557

is now in Policy, and they're marked mandatory, recommended or

558

optional based on the current practice and the behavior of the

559

deb-building tool-chain.

560

561

<item>Elimination of needlessly deep section levels, primarily in the

562

chapter Debian Archive, from which two new chapters were split out,

563

Binary packages and Source packages. What remained was reordered

564

properly, that is, some sects became sects etc.

565

566

<item>Several sections that were redundant, crufty or simply not designed

567

with any sort of vision, were rearranged according to the formula that

568

everything should be either in the same place or properly interlinked.

569

Some things remained split up between different chapters when they

570

talked about different aspects of files: their content, their syntax,

571

and their placement in the file system. In particular, see the new

572

sections about changelog files.

573

<tag>menu policy</tag>

574

<item>Added Games/Simulation and Apps/Education to menu

575

sub-policy

576

577

<item>Debian changelogs should be UTF-8 encoded.

578

579

<item>shared libraries must be linked against all libraries that they

580

use symbols from in the same way that binaries are.

581

582

<item>build-depends-indep need not be satisfied during clean

583

target.

584

</taglist>

585

586

<sect> Version 3.5.10

587

588

589

Released May 2003.

590

591

592

593

<item>packages providing the x-terminal-emulator virtual package

594

ought to ensure that they interpret the command line exactly

595

like xterm does.

596

597

<item>Window managers compliant with the Window Manager Specification

598

Project may add 40 points for ranking in the alternatives

599

</taglist>

600

601

<sect> Version 3.5.9.0

602

603

604

Released Mar 2003.

605

606

607

608

<item>The section describing the Description: package field once again has

609

full details of the long description format.

610

611

<item>Clarified that if a package has non-build-essential

612

build-dependencies, it should have them listed in the Build-Depends

613

and related fields (i.e. it's not merely optional).

614

615

<item>When asked to restart a service that isn't already running,

616

the init script should start the service.

617

618

<item>If the purpose of a package is to provide examples, then the

619

example files can be installed into <file>/usr/share/doc/package</file>

620

(rather than <file>/usr/share/doc/package/examples</file>).

621

</taglist>

622

623

<sect> Version 3.5.8.0

624

625

626

Released Nov 2002.

627

628

629

630

<item>It is no longer necessary to keep a log of changes to the upstream

631

sources in the copyright file. Instead, all such changes should be

632

documented in the changelog file.

633

634

<item><var/Build-Depends/, <var/Build-Conflicts/, <var/Build-Depends-Indep/,

635

and <var/Build-Conflicts-Indep/ must also be satisfied when the clean

636

target is called.

637

<tag>menu policy</tag>

638

<item>A new Apps/Science menu section is available

639

<tag>debconf policy</tag>

640

<item>debconf specification cleared up, various changes.

641

642

<item>It is no longer recommended to create symlinks from nonexistent

643

manual pages to undocumented(7). Missing manual pages for programs

644

are still a bug.

645

</taglist>

646

647

<sect> Version 3.5.7.0

648

649

650

Released Aug 2002.

651

652

653

654

<item>Packages no longer have to ask permission to call MAKEDEV in

655

postinst, merely notifying the user ought to be enough.

656

657

<item>cryptographic software may now be included in the main

658

archive.

659

660

<item>task packages are no longer permitted; tasks are now created by a

661

special Tasks: field in the control file.

662

663

<item>window managers that support netwm can now add 20 points when

664

they add themselves as an alternative for

665

<file>/usr/bin/x-window-manager</file>

666

667

<item>The default compilation options have now changed, one should

668

provide debugging symbols in all cases, and optionally step

669

back optimization to -O0, depending on the DEB_BUILD_OPTIONS

670

environment variable.

671

672

<item>Added mention of build-arch, build-indep, etc, in describing

673

the relationships with `Build-Depends', `Build-Conflicts',

674

`Build-Depends-Indep', and `Build-Conflicts-Indep'. May need to

675

review the new rules.

676

677

<item>Changed rules on how, and when, to invoke ldconfig in maintainer

678

scripts. Long rationale.

679

</taglist>

680

681

682

Added the last note in 3.5.6 upgrading checklist item regarding build

683

rules, please see below

684

685

686

<sect> Version 3.5.6.0

687

688

689

Released Jul 2001.

690

691

692

693

<item>Emacs and TeX are no longer mandated by policy to be priority

694

standard packages

695

696

<item>Programs that access docs need to do so via <file>/usr/share/doc</file>,

697

and not via <file>/usr/doc/</file> as was the policy previously

698

699

<item>Putting documentation in <file>/usr/doc</file> versus

700

<file>/usr/share/doc</file> is now a ``serious'' policy violation.

701

702

<item>For web servers, one should not provide non-local access to the

703

<file>/usr/share/doc</file> hierarchy. If one can't provide access

704

controls for the http://localhost/doc/ directory, then it is preferred

705

that one ask permission to expose that information during the install.

706

707

<item>There are new rules for build-indep/build-arch targets and

708

there is a new Build-Depend-Indep semantic.

709

</taglist>

710

711

<sect> Version 3.5.5.0

712

713

714

Released May 2001.

715

716

717

718

<item>Manpages should not rely on header information to have

719

alternative manpage names available; it should only use

720

symlinks or .so pages to do this

721

</item>

722

723

<item> Clarified note in 3.5.3.0 upgrading checklist regarding

724

examples and templates: this refers only to those examples used

725

by scripts; see section 10.7.3 for the whole story

726

</item>

727

728

<item>Included a new section 10.9.1 describing the use of

729

dpkg-statoverride; this does not have the weight of policy

730

</item>

731

732

<item>Clarify Standards-Version: you don't need to rebuild your

733

packages just to change the Standards-Version!

734

</item>

735

736

<item>Plugins are no longer bound by all the rules of shared

737

libraries

738

</item>

739

<tag>X Windows related things:</tag>

740

741

742

<item>Clarification of priority levels of X Window System related

743

packages

744

</item>

745

746

<item>Rules for defining x-terminal-emulator improved </item>

747

748

<item>X Font policy rewritten: you must read this if you provide

749

fonts for the X Window System

750

</item>

751

752

<item>Packages must not ship <file>/usr/X11R6/lib/X11/app-defaults/</file>

753

</item>

754

755

<item>X-related packages should usually use the regular FHS

756

locations; imake-using packages are exempted from this

757

</item>

758

759

<item>OpenMotif linked binaries have the same rules as

760

OSF/Motif-linked ones

761

</item>

762

</taglist></item>

763

</taglist>

764

765

<sect> Version 3.5.4.0

766

Released Apr 2001.

767

768

769

770

<item>The system-wide mail directory is now /var/mail, no longer

771

/var/spool/mail. Any packages accessing the mail spool should

772

access it via /var/mail and include a suitable Depends field;

773

details in

774

</item>

775

<tag>11.9; perl-policy</tag>

776

<item>The perl policy is now part of Debian policy

777

proper. Perl programs and modules should follow the current Perl

778

policy

779

</item>

780

</taglist>

781

782

<sect> Version 3.5.3.0

783

Released Apr 2001

784

785

786

787

<item>Build-Depends arch syntax has been changed to be less

788

ambiguous. This should not affect any current packages

789

</item>

790

791

<item>Examples and templates files for use by scripts should now live

792

in <file>/usr/share/<package></file> or

793

<file>/usr/lib/<package></file>, with symbolic links from

794

<file>/usr/share/doc/<package>/examples</file> as needed

795

</item>

796

</taglist>

797

798

<sect> Version 3.5.2.0

799

800

Released Feb 2001.

801

802

803

804

<item>X app-defaults directory has moved from

805

<file>/usr/X11R6/lib/X11/app-defaults</file> to

806

<file>/etc/X11/app-defaults</file>

807

</item>

808

</taglist>

809

810

<sect> Version 3.5.1.0

811

812

Released Feb 2001.

813

814

815

816

<item>dpkg-shlibdeps now uses objdump, so shared libraries have to be

817

run through dpkg-shlibdeps as well as executables

818

</item>

819

</taglist>

820

821

<sect> Version 3.5.0.0

822

823

Released Jan 2001.

824

825

826

827

<item>Font packages for the X Window System must now declare a

828

dependency on xutils (>= 4.0.2)

829

</item>

830

</taglist>

831

832

<sect> Version 3.2.1.1

833

834

Released Jan 2001.

835

836

837

838

<item>Daemon startup scripts in <file>/etc/init.d/</file> should not contain

839

modifiable parameters; these should be moved to a file in

840

<file>/etc/default/</file>

841

</item>

842

843

<item>Files in <file>/usr/share/doc</file> must not be referenced by any

844

program. If such files are needed, they must be placed in

845

<file>/usr/share/<package>/</file>, and symbolic links

846

created as required in <file>/usr/share/doc/<package>/</file>

847

</item>

848

849

<item>Much of the packaging manual has now been imported into the

850

policy document

851

</item>

852

</taglist>

853

854

<sect> Version 3.2.1.0

855

856

Released Aug 00.

857

858

859

860

<item>A package of priority standard or higher may provide two

861

binaries, one compiled with support for the X Window System,

862

and the other without

863

</item>

864

</taglist>

865

866

<sect> Version 3.2.0.0

867

868

Released Aug 00.

869

870

871

872

<item>By default executables should not be built with the debugging

873

option -g. Instead, it is recommended to support building the

874

package with debugging information optionally. Details in

875

</item>

876

877

<item>Policy for packages where the upstream uses HTML changelog

878

files has been expanded. In short, a plain text changelog file

879

should always be generated for the upstream changes

880

</item>

881

882

<item>Please note that the new release of the X window system (3.2)

883

shall probably need sweeping changes in policy

884

</item>

885

886

<item>Policy for packages providing the following X-based features

887

has been codified:

888

889

890

<item>X server (virtual package xserver) </item>

891

892

<item>X terminal emulator (virtual package x-terminal-emulator) </item>

893

894

<item>X window manager (virtual package x-window-manager, and

895

<file>/usr/bin/x-window-manager</file> alternative, with priority

896

calculation guidelines)

897

</item>

898

899

<item>X fonts (this section has been written from scratch) </item>

900

901

<item>X application defaults </item>

902

</taglist>

903

</item>

904

905

<item>Policy for packages using the X Window System and FHS issues

906

has been clarified;

907

</item>

908

909

<item>No package may contain or make hard links to conffiles </item>

910

911

<item>Noted that newer dpkg versions do not require extreme care in

912

always creating the shared lib before the symlink, so the unpack

913

order be correct

914

</item>

915

</taglist>

916

917

<sect> Version 3.1.1.0

918

919

Released Nov 1999.

920

921

922

923

<item>Correction to semantics of architecture lists in Build-Depends

924

etc. Should not affect many packages

925

</item>

926

</taglist>

927

928

<sect> Version 3.1.0.0

929

930

Released Oct 1999.

931

932

933

<tag>defunct</tag>

934

<item><file>/usr/doc/<package></file> has to be a symlink pointing to

935

<file>/usr/share/doc/<package></file>, to be maintained by postinst

936

and prerm scripts.

937

</item>

938

939

<item>Introduced source dependencies (Build-Depends, etc.) </item>

940

941

<item><file>/etc/rc.boot</file> has been deprecated in favour of

942

<file>/etc/rcS.d</file>. (Packages should not be touching this directory,

943

but should use update-rc.d instead)

944

</item>

945

946

<item>update-rc.d is now the only allowable way of accessing the

947

<file>/etc/rc?.d/[SK]??*</file> links. Any scripts which manipulate them

948

directly must be changed to use update-rc.d instead. (This is

949

because the file-rc package handles this information in an

950

incompatible way.)

951

</item>

952

953

<item>Architecture-specific examples go in

954

<file>/usr/lib/<package>/examples</file>

955

with symlinks from <file>/usr/share/doc/<package>/examples/*</file>

956

or from <file>/usr/share/doc/<package>/examples</file> itself

957

</item>

958

959

<item>Updated FHS to a 2.1 draft; this reverts <file>/var/state</file> to

960

961

</item>

962

<tag>9.7; mime-policy</tag>

963

<item>Added MIME sub-policy document </item>

964

965

<item>VISUAL is allowed as a (higher priority) alternative to EDITOR

966

</item>

967

968

<item>Modified liblockfile description, which affects

969

mailbox-accessing programs. Please see the policy document for

970

details

971

</item>

972

973

<item>If a package provides a changelog in HTML format, a text-only

974

version should also be included. (Such a version may be prepared

975

using <prgn>lynx -dump -nolist</prgn>.)

976

</item>

977

978

<item>Description of how to handle version numbers based on dates

979

added

980

</item>

981

</taglist>

982

983

<sect> Version 3.0.1.0

984

985

Released Jul 1999.

986

987

988

989

<item>Added the clarification that the .la files are essential for

990

the packages using libtool's libltdl library, in which case the .la

991

files must go in the run-time library package

992

</item>

993

</taglist>

994

995

<sect> Version 3.0.0.0

996

997

Released Jun 1999.

998

999

1000

1001

<item>Debian formally moves from the FSSTND to the FHS. This is a

1002

major change, and the implications of this move are probably

1003

not all known.

1004

</item>

1005

1006

<item>Only 3 digits of the Standards version need be included in

1007

control files, though all four digits are still permitted.

1008

</item>

1009

1010

<item>The location of the GPL has changed to

1011

<file>/usr/share/common-licenses</file>. This may require changing the

1012

1013

other major licenses

1014

</item>

1015

1016

<item>Packages that use libtool to create shared libraries must

1017

include the .la files in the -dev packages

1018

</item>

1019

1020

<item>Use logrotate to rotate log files

1021

</item>

1022

1023

<item>section 5.8 has been rewritten (Programs for the X Window

1024

System)

1025

</item>

1026

<tag>9.6; menu-policy</tag>

1027

<item>There is now an associated menu policy, in a separate document,

1028

that carries the full weight of Debian policy

1029

</item>

1030

1031

<item>Programs which need to modify the files <file>/var/run/utmp</file>,

1032

<file>/var/log/wtmp</file> and <file>/var/log/lastlog</file> must be

1033

installed setgid utmp

1034

</item>

1035

</taglist>

1036

1037

Please note that section numbers below this point may not be up to date

1038

1039

1040

<sect> Version 2.5.0.0

1041

1042

Released Oct 1998.

1043

1044

Policy Manual:

1045

<list>

1046

<item>Rearranged the manual to create a new Section 4, Files

1047

<list>

1048

<item>Section 3.3 ("Files") was moved to Section 4. The Sections

1049

that were Section 4 and Section 5 were moved down to become

1050

Section 5 and Section 6.

1051

</item>

1052

<item>What was Section 5.5 ("Log files") is now a subsection of the

1053

new Section 4 ("Files"), becoming section 4.8, placed after

1054

"Configuration files", moving the Section 4.8 ("Permissions

1055

and owners") to Section 4.9. All subsections of the old

1056

Section 5 after 5.5 were moved down to fill in the number

1057

gap.

1058

</item>

1059

</list></item>

1060

<item>Modified the section about changelog files to accommodate

1061

upstream changelogs which were formatted as HTML. These

1062

upstream changelog files should now be accessible as

1063

<file>/usr/doc/package/changelog.html.gz</file>

1064

</item>

1065

<item>Symlinks are permissible to link the real, or upstream,

1066

changelog name to the Debian mandated name.

1067

</item>

1068

<item>Clarified that HTML documentation should be present in some

1069

package, though not necessarily the main binary package.

1070

</item>

1071

<item>Corrected all references to the location of the copyright

1072

files. The correct location is <file>/usr/doc/package/copyright</file>

1073

</item>

1074

<item>Ratified the architecture specification strings to cater to the

1075

HURD.

1076

</item>

1077

</list>

1078

1079

<sect> Version 2.4.1.0

1080

1081

Released Apr 1998.

1082

1083

<sect1> Policy Manual:

1084

1085

<tag>Updated section 3.3.5 Symbolic links:</tag>

1086

<item>symbolic links within a toplevel directory should be relative,

1087

symbolic links between toplevel directories should be absolute

1088

(cf., Policy Weekly Issue#6, topic 2)

1089

</item>

1090

1091

<tag>Updated section 4.9 Games:</tag>

1092

<item>manpages for games should be installed in <file>/usr/man/man6</file>

1093

(cf., Policy Weekly Issue#6, topic 3)

1094

</item>

1095

</taglist>

1096

1097

<sect1> Packaging Manual:

1098

<list>

1099

<item>Updated prefix of chapter 12, Shared Libraries:

1100

ldconfig must be called in the postinst script if the package

1101

installs shared libraries

1102

(cf., Policy Weekly Issue #6, fixes:bug#20515)

1103

</item>

1104

</list>

1105

1106

<sect> Version 2.4.0.0

1107

1108

Released Jan 1998

1109

1110

1111

<tag>Updated section 3.3.4 Scripts:</tag>

1112

1113

<item>/bin/sh may be any POSIX compatible shell

1114

<item>scripts including bashisms have to specify <file>/bin/bash</file>

1115

as interpreter

1116

<item>scripts which create files in world-writable directories

1117

(e.g., in <file>/tmp</file>) should use tempfile or mktemp for creating

1118

the directory

1119

</list></item>

1120

1121

<tag>Updated section 3.3.5 Symbolic Links:</tag>

1122

<item>symbolic links referencing compressed files must have the same

1123

file extension as the referenced file

1124

</item>

1125

1126

<tag>Updated section 3.3.6 Device files:</tag>

1127

<item><file>/dev/tty*</file> serial devices should be used instead of

1128

1129

</item>

1130

1131

<tag>Updated section 3.4.2 Writing the scripts in <file>/etc/init.d</file>:

1132

1133

<item>all <file>/etc/init.d</file> scripts have to provide the following

1134

options: start, stop, restart, force-reload

1135

<item>the reload option is optional and must never stop and restart

1136

the service

1137

</list></item>

1138

1139

<tag>Updated section 3.5 Cron jobs:

1140

<item>cron jobs that need to be executed more often than daily should

1141

be installed into <file>/etc/cron.d</file>

1142

</item>

1143

1144

<tag>Updated section 3.7 Menus:

1145

<item>removed section about how to register HTML docs to `menu'

1146

(the corresponding section in 4.4, Web servers and applications,

1147

has been removed in policy 2.2.0.0 already, so this one was

1148

obsolete)

1149

</item>

1150

1151

<tag>New section 3.8 Keyboard configuration:

1152

<item>details about how the backspace and delete keys should be

1153

handled

1154

</item>

1155

1156

<tag>New section 3.9 Environment variables:

1157

<item>no program must depend on environment variables to get a

1158

reasonable default configuration

1159

</item>

1160

1161

<tag>New section 4.6 News system configuration:

1162

<item><file>/etc/news/organization</file> and <file>/etc/news/server</file>

1163

should be supported by all news servers and clients

1164

</item>

1165

1166

<tag>Updated section 4.7 Programs for the X Window System:

1167

1168

<item>programs requiring a non-free Motif library should be provided

1169

as foo-smotif and foo-dmotif package

1170

</item>

1171

<item>if lesstif works reliably for such program, it should be linked

1172

against lesstif and not against a non-free Motif library

1173

</item>

1174

</list></item>

1175

1176

<tag>Updated section 4.9 Games:

1177

<item>games for X Windows have to be installed in <file>/usr/games</file>,

1178

just as non-X games

1179

</item>

1180

</taglist>

1181

1182

<sect> Version 2.3.0.1, 2.3.0.0

1183

1184

Released Sep 1997.

1185

1186

<list>

1187

<item>new section `4.2 Daemons' including rules for

1188

<file>/etc/services</file>, <file>/etc/protocols</file>,

1189

<file>/etc/rpc</file>, and <file>/etc/inetd.conf</file>

1190

</item>

1191

1192

<item>updated section about `Configuration files':

1193

packages may not touch other packages' configuration files

1194

</item>

1195

1196

<item>MUAs and MTAs have to use liblockfile</item>

1197

</list>

1198

1199

<sect> Version 2.2.0.0

1200

1201

Released July 1997.

1202

1203

<list>

1204

<item>added section 4.1 `Architecture specification strings':

1205

use

1206

<arch>-linux

1207

where <arch> is one of the following:

1208

i386, alpha, arm, m68k, powerpc, sparc.

1209

</item>

1210

1211

<item>detailed rules for <file>/usr/local</file></item>

1212

1213

1214

1215

<item>editor/pager policy</item>

1216

1217

1218

1219

<item>device files</item>

1220

1221

<item>don't install shared libraries as executable</item>

1222

1223

<item>app-defaults files may not be conffiles</item>

1224

</list>

1225

1226

<sect> Version 2.1.3.2, 2.1.3.1, 2.1.3.0

1227

1228

Released Mar 1997.

1229

1230

<list>

1231

<item>two programs with different functionality must not have the

1232

same name </item>

1233

1234

<item>"Webstandard 3.0"</item>

1235

1236

<item>"Standard for Console Messages"</item>

1237

1238

<item>Libraries should be compiled with `-D_REENTRANT'</item>

1239

1240

<item>Libraries should be stripped with <prgn>strip --strip-unneeded</prgn>

1241

</item>

1242

</list>

1243

1244

<sect> Version 2.1.2.2, 2.1.2.1, 2.1.2.0

1245

1246

Released Nov 1996.

1247

1248

<list>

1249

<item>Some changes WRT shared libraries

1250

</list>

1251

1252

<sect> Version 2.1.1.0

1253

1254

Released Sep 1996.

1255

1256

<list>

1257

<item>No hard links in source packages</item>

1258

1259

<item>Do not use <prgn>dpkg-divert</prgn> or <prgn>update-alternatives</prgn>

1260

without consultation </item>

1261

1262

<item>Shared libraries must be installed stripped </item>

1263

</list>

1264

1265

<sect> Version 2.1.0.0

1266

1267

Released Aug 1996.

1268

1269

<list>

1270

<item>Upstream changelog must be installed too </item>

1271

</list>

1272

</book>

1273

</debiandoc>

Older »