~ubuntu-branches/ubuntu/raring/developers-reference/raring-proposed : revision 4

1

<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [

2

<!-- include version information so we don't have to hard code it

3

within the document -->

4

<!ENTITY % versiondata SYSTEM "version.ent"> %versiondata;

5

6

<!ENTITY % commondata SYSTEM "common.ent" > %commondata;

7

<!ENTITY % dynamicdata SYSTEM "dynamic.ent" > %dynamicdata;

8

9

10

<!ENTITY cvs-rev "$Revision: 1.315 $">

11

12

<!-- if you are translating this document, please notate the CVS

13

revision of the original developer's reference in cvs-en-rev -->

14

15

16

17

<!ENTITY FIXME "FIXME: ">

18

19

]>

20

21

<book>

22

<title>Debian Developer's Reference

23

24

<author>Developer's Reference Team &email-devel-ref;

25

<author>Andreas Barth

26

<author>Adam Di Carlo

27

<author>Rapha�l Hertzog

28

<author>Christian Schwarz

29

<author>Ian Jackson

30

<version>ver. &version;, &date-en;

31

32

33

34

35

36

37

38

39

40

41

42

This manual is free software; you may redistribute it and/or modify it

43

under the terms of the GNU General Public License as published by the

44

Free Software Foundation; either version 2, or (at your option) any

45

later version.

46

47

This is distributed in the hope that it will be useful, but

48

without any warranty; without even the implied warranty of

49

merchantability or fitness for a particular purpose. See the GNU

50

General Public License for more details.

51

52

A copy of the GNU General Public License is available as &file-GPL; in

53

the &debian-formal; distribution or on the World Wide Web at <url

54

id="&url-gpl;" name="the GNU web site">. You can also obtain it by

55

writing to the &fsf-addr;.

56

57

<![ %htmltext [

58

59

If you want to print this reference, you should use the <url

60

id="developers-reference.pdf" name="pdf version">.

61

This page is also available in <url id="index.fr.html" name="French">.

62

]]>

63

64

65

66

<chapt id="scope">Scope of This Document

67

68

The purpose of this document is to provide an overview of the

69

recommended procedures and the available resources for Debian

70

developers.

71

72

73

74

The procedures discussed within include how to become a maintainer

75

(<ref id="new-maintainer">); how to create new packages

76

(<ref id="newpackage">) and how to upload packages (<ref id="upload">);

77

how to handle bug reports (<ref id="bug-handling">); how to move,

78

remove, or orphan packages (<ref id="archive-manip">); how to port

79

packages (<ref id="porting">); and how and when to do interim

80

releases of other maintainers' packages (<ref id="nmu">).

81

82

The resources discussed in this reference include the mailing lists

83

(<ref id="mailing-lists">) and servers (<ref id="server-machines">); a

84

discussion of the structure of the Debian archive (<ref

85

id="archive">); explanation of the different servers which accept

86

package uploads (<ref id="upload-ftp-master">); and a discussion of

87

resources which can help maintainers with the quality of their

88

packages (<ref id="tools">).

89

90

It should be clear that this reference does not discuss the technical

91

details of Debian packages nor how to generate them.

92

Nor does this reference detail the standards to which Debian software

93

must comply. All of such information can be found in the <url

94

id="&url-debian-policy;" name="Debian Policy Manual">.

95

96

Furthermore, this document is not an expression of formal

97

policy. It contains documentation for the Debian system and

98

generally agreed-upon best practices. Thus, it is not what is called a

99

``normative'' document.

100

101

102

<chapt id="new-maintainer">Applying to Become a Maintainer

103

104

<sect id="getting-started">Getting started

105

106

So, you've read all the documentation, you've gone through the <url

107

id="&url-newmaint-guide;" name="Debian New Maintainers' Guide">,

108

understand what everything in the <package>hello</package> example

109

package is for, and you're about to Debianize your favorite piece of

110

software. How do you actually become a Debian developer so that your

111

work can be incorporated into the Project?

112

113

Firstly, subscribe to &email-debian-devel; if you haven't already.

114

Send the word <tt>subscribe</tt> in the Subject of an email

115

to &email-debian-devel-req;. In case of problems, contact the list

116

administrator at &email-listmaster;. More information on available

117

mailing lists can be found in <ref id="mailing-lists">.

118

&email-debian-devel-announce; is another list which is mandatory

119

for anyone who wishes to follow Debian's development.

120

121

You should subscribe and lurk (that is, read without posting) for a

122

bit before doing any coding, and you should post about your intentions

123

to work on something to avoid duplicated effort.

124

125

Another good list to subscribe to is &email-debian-mentors;. See <ref

126

id="mentors"> for details. The IRC channel <tt>#debian</tt> can also be

127

helpful; see <ref id="irc-channels">.

128

129

130

When you know how you want to contribute to &debian-formal;, you

131

should get in contact with existing Debian maintainers who are working

132

on similar tasks. That way, you can learn from experienced developers.

133

For example, if you are interested in packaging existing software for

134

Debian, you should try to get a sponsor. A sponsor will work together

135

with you on your package and upload it to the Debian archive once they

136

are happy with the packaging work you have done. You can find a sponsor

137

by mailing the &email-debian-mentors; mailing list, describing your

138

package and yourself and asking for a sponsor (see <ref id="sponsoring">

139

and <url id="&url-mentors;"> for more information on sponsoring).

140

On the other hand, if you are

141

interested in porting Debian to alternative architectures or kernels

142

you can subscribe to port specific mailing lists and ask there how to

143

get started. Finally, if you are interested in documentation or

144

Quality Assurance (QA) work you can join maintainers already working on

145

these tasks and submit patches and improvements.

146

147

148

One pitfall could be a too-generic local part in your mailadress:

149

Terms like mail, admin, root, master should be avoided, please

150

see <url id="http://www.debian.org/MailingLists/"> for details.

151

152

153

<sect id="mentors">Debian mentors and sponsors

154

155

The mailing list &email-debian-mentors; has been set up for novice

156

maintainers who seek help with initial packaging and other

157

developer-related issues. Every new developer is invited to subscribe

158

to that list (see <ref id="mailing-lists"> for details).

159

160

Those who prefer one-on-one help (e.g., via private email) should also

161

post to that list and an experienced developer will volunteer to help.

162

163

In addition, if you have some packages ready for inclusion in Debian,

164

but are waiting for your new maintainer application to go through, you

165

might be able find a sponsor to upload your package for you. Sponsors

166

are people who are official Debian Developers, and who are willing to

167

criticize and upload your packages for you.

168

<!-- FIXME - out of order

169

Those who are seeking a

170

sponsor can request one at <url id="&url-sponsors;">.

171

-->

172

Please read the

173

unofficial debian-mentors FAQ at <url id="&url-mentors;"> first.

174

175

If you wish to be a mentor and/or sponsor, more information is

176

available in <ref id="newmaint">.

177

178

179

<sect id="registering">Registering as a Debian developer

180

181

Before you decide to register with &debian-formal;, you will need to

182

read all the information available at the <url id="&url-newmaint;"

183

name="New Maintainer's Corner">. It describes in detail the

184

preparations you have to do before you can register to become a Debian

185

developer.

186

187

For example, before you apply, you have to read the <url

188

id="&url-social-contract;" name="Debian Social Contract">.

189

Registering as a developer means that you agree with and pledge to

190

uphold the Debian Social Contract; it is very important that

191

maintainers are in accord with the essential ideas behind

192

&debian-formal;. Reading the <url id="&url-gnu-manifesto;" name="GNU

193

Manifesto"> would also be a good idea.

194

195

The process of registering as a developer is a process of verifying

196

your identity and intentions, and checking your technical skills. As

197

the number of people working on &debian-formal; has grown to over

198

&number-of-maintainers; and our systems are used in several

199

very important places, we have to be careful about being compromised.

200

Therefore, we need to verify new maintainers before we can give them

201

accounts on our servers and let them upload packages.

202

203

Before you actually register you should have shown that you can do

204

competent work and will be a good contributor.

205

You show this by submitting patches through the Bug Tracking System

206

and having a package

207

sponsored by an existing Debian Developer for a while.

208

Also, we expect that

209

contributors are interested in the whole project and not just in

210

maintaining their own packages. If you can help other maintainers by

211

providing further information on a bug or even a patch, then do so!

212

213

Registration requires that you are familiar with Debian's philosophy

214

and technical documentation. Furthermore, you need a GnuPG key which

215

has been signed by an existing Debian maintainer. If your GnuPG key

216

is not signed yet, you should try to meet a Debian Developer in

217

person to get your key signed. There's a <url id="&url-gpg-coord;"

218

name="GnuPG Key Signing Coordination page"> which should help you find

219

a Debian Developer close to you.

220

(If there is no Debian Developer close to you,

221

alternative ways to pass the ID check may be permitted

222

as an absolute exception on a case-by-case-basis.

223

See the <url id="&url-newmaint-id;" name="identification page">

224

for more information.)

225

226

227

If you do not have an OpenPGP key yet, generate one. Every developer

228

needs an OpenPGP key in order to sign and verify package uploads. You

229

should read the manual for the software you are using, since it has

230

much important information which is critical to its security. Many

231

more security failures are due to human error than to software failure

232

or high-powered spy techniques. See <ref id="key-maint"> for more

233

information on maintaining your public key.

234

235

Debian uses the <prgn>GNU Privacy Guard</prgn> (package

236

<package>gnupg</package> version 1 or better) as its baseline standard.

237

You can use some other implementation of OpenPGP as well. Note that

238

OpenPGP is an open standard based on <url id="&url-rfc2440;" name="RFC

239

2440">.

240

241

You need a version 4 key for use in Debian Development.

242

Your key length must be at least 1024

243

bits; there is no reason to use a smaller key, and doing so would be

244

much less secure.

245

<footnote>Version 4 keys are keys conforming to

246

the OpenPGP standard as defined in RFC 2440. Version 4 is the key

247

type that has always been created when using GnuPG. PGP versions

248

since 5.x also could create v4 keys, the other choice having beein

249

pgp 2.6.x compatible v3 keys (also called "legacy RSA" by PGP).

250

251

Version 4 (primary) keys can either use the RSA or the DSA algorithms,

252

so this has nothing to do with GnuPG's question about "which kind

253

of key do you want: (1) DSA and Elgamal, (2) DSA (sign only), (5)

254

RSA (sign only)". If you don't have any special requirements just pick

255

the defailt.

256

257

The easiest way to tell whether an existing key is a v4 key or a v3

258

(or v2) key is to look at the fingerprint:

259

Fingerprints of version 4 keys are the SHA-1 hash of some key matieral,

260

so they are 40 hex digits, usually grouped in blocks of 4. Fingerprints

261

of older key format versions used MD5 and are generally shown in blocks

262

of 2 hex digits. For example if your fingerprint looks like

263

264

then it's a v4 key.

265

266

Another possibility is to pipe the key into <prgn>pgpdump</prgn>,

267

which will say something like "Public Key Packet - Ver 4".

268

269

Also note that your key must be self-signed (i.e. it has to sign

270

all its own user IDs; this prevents user ID tampering). All

271

modern OpenPGP software does that automatically, but if you

272

have an older key you may have to manually add those signatures.

273

</footnote>

274

275

If your public key isn't on a public key server such as &pgp-keyserv;,

276

please read the documentation available at

277

<url id="&url-newmaint-id;" name="NM Step 2: Identification">.

278

That document contains instructions on how to put your key on the

279

public key servers. The New Maintainer Group will put your public key

280

on the servers if it isn't already there.

281

282

Some countries restrict the use of cryptographic software by their

283

citizens. This need not impede one's activities as a Debian package

284

maintainer however, as it may be perfectly legal to use cryptographic

285

products for authentication, rather than encryption purposes.

286

If you live in a country where use of

287

cryptography even for authentication is forbidden

288

then please contact us so we can make special arrangements.

289

290

To apply as a new maintainer, you need an existing Debian Developer

291

to support your application (an advocate). After you have

292

contributed to Debian for a while, and you want to apply to become a

293

registered developer, an existing developer with whom you

294

have worked over the past months has to express their belief that you

295

can contribute to Debian successfully.

296

297

When you have found an advocate, have your GnuPG key signed and have

298

already contributed to Debian for a while, you're ready to apply.

299

You can simply register on our <url id="&url-newmaint-apply;"

300

name="application page">. After you have signed up, your advocate

301

has to confirm your application. When your advocate has completed

302

this step you will be assigned an Application Manager who will

303

go with you through the necessary steps of the New Maintainer process.

304

You can always check your status on the <url id="&url-newmaint-db;"

305

name="applications status board">.

306

307

For more details, please consult <url id="&url-newmaint;" name="New

308

Maintainer's Corner"> at the Debian web site. Make sure that you

309

are familiar with the necessary steps of the New Maintainer process

310

before actually applying. If you are well prepared, you can save

311

a lot of time later on.

312

313

314

<chapt id="developer-duties">Debian Developer's Duties

315

316

<sect id="user-maint">Maintaining your Debian information

317

318

There's a LDAP database containing information about Debian developers at

319

<url id="&url-debian-db;">. You should enter your information there and

320

update it as it changes. Most notably, make sure that the address where your

321

debian.org email gets forwarded to is always up to date, as well as the

322

address where you get your debian-private subscription if you choose to

323

subscribe there.

324

325

For more information about the database, please see <ref id="devel-db">.

326

327

328

329

<sect id="key-maint">Maintaining your public key

330

331

Be very careful with your private keys. Do not place them on any

332

public servers or multiuser machines, such as the Debian servers

333

(see <ref id="server-machines">). Back your keys up; keep a copy offline.

334

Read the documentation that comes with your software; read the <url

335

id="&url-pgp-faq;" name="PGP FAQ">.

336

337

You need to ensure not only that your key is secure against being stolen,

338

but also that it is secure against being lost. Generate and make a copy

339

(best also in paper form) of your revocation certificate; this is needed if

340

your key is lost.

341

342

If you add signatures to your public key, or add user identities, you

343

can update the Debian key ring by sending your key to the key server at

344

<tt>&keyserver-host;</tt>.

345

346

If you need to add a completely new key or remove an old key, you need

347

to get the new key signed by another developer.

348

If the old key is compromised or invalid, you

349

also have to add the revocation certificate. If there is no real

350

reason for a new key, the Keyring Maintainers might reject the new key.

351

Details can be found at

352

<url id="http://keyring.debian.org/replacing_keys.html">.

353

354

The same key extraction routines discussed in <ref id="registering">

355

apply.

356

357

You can find a more in-depth discussion of Debian key maintenance in

358

the documentation of the <package>debian-keyring</package> package.

359

360

361

<sect id="voting">Voting

362

363

Even though Debian isn't really a democracy, we use a democratic

364

process to elect our leaders and to approve general resolutions.

365

These procedures are defined by the

366

<url id="&url-constitution;" name="Debian Constitution">.

367

368

Other than the yearly leader election, votes are not routinely held, and

369

they are not undertaken lightly. Each proposal is first discussed on

370

the &email-debian-vote; mailing list and it requires several endorsements

371

before the project secretary starts the voting procedure.

372

373

You don't have to track the pre-vote discussions, as the secretary will

374

issue several calls for votes on &email-debian-devel-announce; (and all

375

developers are expected to be subscribed to that list). Democracy doesn't

376

work well if people don't take part in the vote, which is why we encourage

377

all developers to vote. Voting is conducted via GPG-signed/encrypted email

378

messages.

379

380

The list of all proposals (past and current) is available on the

381

<url id="&url-vote;" name="Debian Voting Information"> page, along with

382

information on how to make, second and vote on proposals.

383

384

385

<sect id="inform-vacation">Going on vacation gracefully

386

387

It is common for developers to have periods of absence, whether those are

388

planned vacations or simply being buried in other work. The important thing

389

to notice is that other developers need to know that you're on vacation

390

so that they can do whatever is needed if a problem occurs with your

391

packages or other duties in the project.

392

393

Usually this means that other developers are allowed to NMU (see

394

<ref id="nmu">) your package if a big problem (release critical bug,

395

security update, etc.) occurs while you're on vacation. Sometimes it's

396

nothing as critical as that, but it's still appropriate to let others

397

know that you're unavailable.

398

399

In order to inform the other developers, there are two things that you should do.

400

First send a mail to &email-debian-private; with "[VAC] " prepended to the

401

subject of your message<footnote>This is so that the message can be easily

402

filtered by people who don't want to read vacation notices.</footnote>

403

and state the period of time when you will be on vacation. You can also give

404

some special instructions on what to do if a problem occurs.

405

406

The other thing to do is to mark yourself as "on vacation" in the

407

<qref id="devel-db">Debian developers' LDAP database</qref> (this

408

information is only accessible to Debian developers).

409

Don't forget to remove the "on vacation" flag when you come back!

410

411

Ideally, you should sign up at the

412

413

when booking a holiday and check if anyone there is looking for signing.

414

This is especially important when people go to exotic places

415

where we don't have any developers yet but

416

where there are people who are interested in applying.

417

418

419

<sect id="upstream-coordination">Coordination with upstream developers

420

421

A big part of your job as Debian maintainer will be to stay in contact

422

with the upstream developers. Debian users will sometimes report bugs

423

that are not specific to Debian to our bug tracking system. You

424

have to forward these bug reports to the upstream developers so that

425

they can be fixed in a future upstream release.

426

427

While it's not your job to fix non-Debian specific bugs, you may freely

428

do so if you're able. When you make such fixes, be sure to pass them on

429

to the upstream maintainers as well. Debian users and developers will

430

sometimes submit patches to fix upstream bugs — you should evaluate

431

and forward these patches upstream.

432

433

If you need to modify the upstream sources in order to build a policy

434

compliant package, then you should propose a nice fix to the upstream

435

developers which can be included there, so that you won't have to

436

modify the sources of the next upstream version. Whatever changes you

437

need, always try not to fork from the upstream sources.

438

439

440

<sect id="rc-bugs">Managing release-critical bugs

441

442

Generally you should deal with bug reports on your packages as described in

443

<ref id="bug-handling">. However, there's a special category of bugs that

444

you need to take care of — the so-called release-critical bugs (RC bugs).

445

All bug reports that have severity critical, grave or

446

serious are considered to have an impact on whether the package can

447

be released in the next stable release of Debian.

448

These bugs can delay the Debian release

449

and/or can justify the removal of a package at freeze time. That's why

450

these bugs need to be corrected as quickly as possible.

451

452

Developers who are part of the <url id="&url-debian-qa;"

453

name="Quality Assurance"> group are following all such bugs, and trying

454

to help whenever possible. If, for any reason, you aren't able fix an

455

RC bug in a package of yours within 2 weeks, you should either ask for help

456

by sending a mail to the Quality Assurance (QA) group

457

&email-debian-qa;, or explain your difficulties and present a plan to fix

458

them by sending a mail to the bug report. Otherwise, people

459

from the QA group may want to do a Non-Maintainer Upload (see

460

<ref id="nmu">) after trying to contact you (they might not wait as long as

461

usual before they do their NMU if they have seen no recent activity from you

462

in the BTS).

463

464

465

<sect>Retiring

466

467

If you choose to leave the Debian project, you should make sure you do

468

the following steps:

469

470

<item>

471

Orphan all your packages, as described in <ref id="orphaning">.

472

<item>

473

Send an gpg-signed email about why you are leaving the project to

474

&email-debian-private;.

475

<item>

476

Notify the Debian key ring maintainers that you are leaving by

477

emailing to &email-debian-keyring;.

478

</enumlist>

479

480

481

482

<chapt id="resources">Resources for Debian Developers

483

484

In this chapter you will find a very brief road map of the Debian

485

mailing lists, the Debian machines

486

which may be available to you as a developer, and all the other

487

resources that are available to help you in your maintainer work.

488

489

<sect id="mailing-lists">Mailing lists

490

491

Much of the conversation between Debian developers (and users) is managed

492

through a wide array of mailing lists we host at

493

<tt><url id="http://&lists-host;/" name="&lists-host;"></tt>.

494

To find out more on how to subscribe or unsubscribe, how to post and how not

495

to post, where to find old posts and how to search them, how to contact the

496

list maintainers and see various other information about the mailing lists,

497

please read <url id="&url-debian-lists;">. This section will only cover

498

aspects of mailing lists that are of particular interest to developers.

499

500

<sect1 id="mailing-lists-rules">Basic rules for use

501

502

When replying to messages on the mailing list, please do not send a

503

carbon copy (<tt>CC</tt>) to the original poster unless they explicitly

504

request to be copied. Anyone who posts to a mailing list should read

505

it to see the responses.

506

507

Cross-posting (sending the same message to multiple lists) is discouraged.

508

As ever on the net, please trim down the quoting of articles you're

509

replying to. In general, please adhere to the usual conventions for

510

posting messages.

511

512

Please read the <url name="code of conduct" id="&url-debian-lists;#codeofconduct">

513

for more information.

514

515

<sect1 id="core-devel-mailing-lists">Core development mailing lists

516

517

The core Debian mailing lists that developers should use are:

518

<list>

519

<item>&email-debian-devel-announce;, used to announce important things to

520

developers.

521

All developers are expected to be subscribed to this list.

522

</item>

523

<item>&email-debian-devel;, used to discuss various development related

524

technical issues.

525

</item>

526

<item>&email-debian-policy;, where the Debian Policy is discussed and

527

voted on.

528

</item>

529

<item>&email-debian-project;, used to discuss various non-technical

530

issues related to the project.

531

</item>

532

</list>

533

534

There are other mailing lists available for a variety of special topics;

535

see <url id="http://&lists-host;/"> for a list.

536

537

<sect1 id="mailing-lists-special">Special lists

538

539

&email-debian-private; is a special mailing list for private

540

discussions amongst Debian developers. It is meant to be used for

541

posts which for whatever reason should not be published publicly.

542

As such, it is a low volume list, and users are urged not to use

543

&email-debian-private; unless it is really necessary. Moreover, do

544

not forward email from that list to anyone. Archives of this

545

list are not available on the web for obvious reasons, but you can see

546

them using your shell account on <tt>lists.debian.org</tt> and looking

547

in the <file>~debian/archive/debian-private</file> directory.

548

549

&email-debian-email; is a special mailing list used as a grab-bag

550

for Debian related correspondence such as contacting upstream authors

551

about licenses, bugs, etc. or discussing the project with others where it

552

might be useful to have the discussion archived somewhere.

553

554

<sect1 id="mailing-lists-new">Requesting new development-related lists

555

556

Before requesting a mailing list that relates to the development of a

557

package (or a small group of related packages), please consider if using

558

an alias (via a .forward-aliasname file on master.debian.org, which

559

translates into a reasonably nice <var>you-aliasname@debian.org</var>

560

address) or a self-managed mailing list on <qref id="alioth">Alioth</qref>

561

is more appropriate.

562

563

If you decide that a regular mailing list on lists.debian.org is really what

564

you want, go ahead and fill in a request, following <url name="the HOWTO"

565

id="&url-debian-lists-new;">.

566

567

<sect id="irc-channels">IRC channels

568

569

Several IRC channels are dedicated to Debian's development. They are mainly

570

hosted on the <url id="&url-oftc;" name="Open and free technology community

571

(OFTC)"> network. The <tt>irc.debian.org</tt> DNS entry is an alias to

572

<tt>irc.oftc.net</tt>.

573

574

The main channel for Debian in general is #debian. This is a large,

575

general-purpose channel where users can find recent news in the topic and

576

served by bots. #debian is for English speakers; there are also

577

#debian.de, #debian-fr, #debian-br and other

578

similarly named channels for speakers of other languages.

579

580

The main channel for Debian development is #debian-devel.

581

It is a very active channel since usually over 150 people are always

582

logged in. It's a channel for people who work

583

on Debian, it's not a support channel (there's #debian for that).

584

It is however open to anyone who wants to lurk (and learn). Its topic is

585

commonly full of interesting information for developers.

586

587

Since #debian-devel is an open channel, you

588

should not speak there of issues that are discussed in

589

&email-debian-private;. There's another channel for this purpose,

590

it's called #debian-private and it's protected by a key.

591

This key is available in the archives of debian-private in

592

<file>master.debian.org:&file-debian-private-archive;</file>,

593

just <prgn>zgrep</prgn> for #debian-private in

594

all the files.

595

596

There are other additional channels dedicated to specific subjects.

597

#debian-bugs is used for coordinating bug squashing parties.

598

#debian-boot is used to coordinate the work on the debian-installer.

599

#debian-doc is

600

occasionally used to talk about documentation, like the document you are

601

reading. Other channels are dedicated to an architecture or a set of

602

packages: #debian-bsd, #debian-kde, #debian-jr,

603

#debian-edu,

604

#debian-sf (SourceForge package), #debian-oo (OpenOffice

605

package) ...

606

607

Some non-English developers' channels exist as well, for example

608

#debian-devel-fr for

609

French speaking people interested in Debian's development.

610

611

Channels dedicated to Debian also exist on other IRC networks, notably on

612

the <url id="&url-openprojects;" name="freenode"> IRC network, which was

613

pointed at by the <tt>irc.debian.org</tt> alias until 4th June 2006.

614

615

To get a cloak on freenode, you send Jörg Jaspert <joerg@debian.org>

616

a signed mail where you tell what your nick is.

617

Put "cloak" somewhere in the Subject: header.

618

The nick should be registered:

619

<url id="http://freenode.net/faq.shtml#nicksetup" name="Nick Setup Page">.

620

The mail needs to be signed by a key in the Debian keyring.

621

Please see

622

623

for more information about cloaks.

624

625

626

<sect id="doc-rsrcs">Documentation

627

628

This document contains a lot of information

629

which is useful to Debian developers,

630

but it cannot contain everything. Most of the other interesting documents

631

are linked from <url id="&url-devel-docs;" name="The Developers' Corner">.

632

Take the time to browse all the links, you will learn many more things.

633

634

635

<sect id="server-machines">Debian machines

636

637

Debian has several computers working as servers, most of which serve

638

critical functions in the Debian project. Most of the machines are used

639

for porting activities, and they all have a permanent connection to the

640

Internet.

641

642

Most of the machines are available for individual developers to use,

643

as long as the developers follow the rules set forth in the

644

<url name="Debian Machine Usage Policies" id="&url-dmup;">.

645

646

Generally speaking, you can use these machines for Debian-related purposes

647

as you see fit. Please be kind to system administrators, and do not use

648

up tons and tons of disk space, network bandwidth, or CPU without first

649

getting the approval of the system administrators. Usually these machines are run by

650

volunteers.

651

652

Please take care to protect your Debian passwords and SSH keys installed on

653

Debian machines. Avoid login or upload methods which send passwords over

654

the Internet in the clear, such as telnet, FTP, POP etc.

655

656

Please do not put any material that doesn't relate to Debian on the Debian

657

servers, unless you have prior permission.

658

659

The current list of Debian machines is available at

660

<url id="&url-devel-machines;">. That web page contains machine names,

661

contact information, information about who can log in, SSH keys etc.

662

663

If you have a problem with the operation of a Debian server, and you

664

think that the system operators need to be notified of this problem,

665

the Debian system administrator team is reachable at

666

<email>debian-admin@lists.debian.org</email>.

667

668

If you have a problem with a certain service, not related to the system

669

administration (such as packages to be removed from the archive,

670

suggestions for the web site, etc.),

671

generally you'll report a bug against a ``pseudo-package''. See <ref

672

id="submit-bug"> for information on how to submit bugs.

673

674

Some of the core servers are restricted, but the information from there

675

is mirrored to another server.

676

677

<sect1 id="servers-bugs">The bugs server

678

679

<tt>&bugs-host;</tt> is the canonical location for the Bug Tracking

680

System (BTS).

681

682

It is restricted; a mirror is available on <tt>merkel</tt>.

683

684

If you plan on doing some statistical analysis or

685

processing of Debian bugs, this would be the place to do it. Please

686

describe your plans on &email-debian-devel; before implementing

687

anything, however, to reduce unnecessary duplication of effort or

688

wasted processing time.

689

690

<sect1 id="servers-ftp-master">The ftp-master server

691

692

The <tt>ftp-master.debian.org</tt> server holds the canonical copy of the Debian

693

archive (excluding the non-US packages). Generally, package uploads

694

go to this server; see <ref id="upload">.

695

696

It is restricted; a mirror is available on <tt>merkel</tt>.

697

698

Problems with the Debian FTP archive generally need to be reported as

699

bugs against the <package>ftp.debian.org</package> pseudo-package or

700

an email to &email-ftpmaster;, but also see the procedures in

701

<ref id="archive-manip">.

702

703

<sect1 id="servers-non-us">The non-US server

704

705

The non-US server <tt>non-us.debian.org</tt>

706

was discontinued with the release of sarge. The pseudo-package

707

<package>nonus.debian.org</package>

708

still exists for now.

709

710

<sect1 id="servers-www">The www-master server

711

712

The main web server is <tt>www-master.debian.org</tt>.

713

It holds the official web pages, the face

714

of Debian for most newbies.

715

716

If you find a problem with the Debian web server, you should generally

717

submit a bug against the pseudo-package,

718

<package>www.debian.org</package>. Remember to check whether or not someone

719

else has already reported the problem to the

720

<url id="http://&bugs-host;/www.debian.org" name="Bug Tracking System">.

721

722

<sect1 id="servers-people">The people web server

723

724

<tt>people.debian.org</tt> is the server used

725

for developers' own web pages about anything related to Debian.

726

727

If you have some Debian-specific information which you want to serve

728

on the web, you can do this by putting material in the

729

<file>public_html</file> directory under your home directory on

730

<tt>people.debian.org</tt>.

731

This will be accessible at the URL

732

<tt>http://people.debian.org/~<var>your-user-id</var>/</tt>.

733

734

You should only use this particular location because it will be backed up,

735

whereas on other hosts it won't.

736

737

Usually the only reason to use a different host is when you need to publish

738

materials subject to the U.S. export restrictions, in which case you can use

739

one of the other servers located outside the United States.

740

741

Send mail to &email-debian-devel; if you have any questions.

742

743

<sect1 id="servers-cvs">The CVS server

744

745

746

Our CVS server is located on <tt>cvs.debian.org</tt>.

747

748

If you need to use a publicly accessible CVS

749

server, for instance, to help coordinate work on a package between

750

many different developers, you can request a CVS area on the server.

751

752

Generally, <tt>cvs.debian.org</tt> offers a combination of local CVS

753

access, anonymous client-server read-only access, and full

754

client-server access through <prgn>ssh</prgn>. Also, the CVS area can

755

be accessed read-only via the Web at <url id="&url-cvsweb;">.

756

757

To request a CVS area, send a request via email to

758

&email-debian-admin;. Include the name of the requested CVS area,

759

the Debian account that should own the CVS root area, and why you need it.

760

761

<sect1 id="dchroot">chroots to different distributions

762

763

On some machines, there are chroots to different distributions available.

764

You can use them like this:

765

766

767

vore% dchroot unstable

768

Executing shell in chroot: /org/vore.debian.org/chroots/user/unstable

769

</example>

770

771

In all chroots, the normal user home directories are available.

772

You can find out which chroots are available via

773

<tt>&url-devel-machines;</tt>.

774

775

776

<sect id="devel-db">The Developers Database

777

778

The Developers Database, at <url id="&url-debian-db;">, is an LDAP

779

directory for managing Debian developer attributes. You can use this

780

resource to search the list of Debian developers.

781

Part of this information is also available through

782

the finger service on Debian servers, try

783

<prgn>finger yourlogin@db.debian.org</prgn> to see what it reports.

784

785

Developers can <url name="log into the database" id="&url-debian-db-login;">

786

to change various information about themselves, such as:

787

<list>

788

<item>forwarding address for your debian.org email

789

<item>subscription to debian-private

790

<item>whether you are on vacation

791

<item>personal information such as your address, country,

792

the latitude and longitude of the place where you live

793

for use in <url name="the world map of Debian developers"

794

id="&url-worldmap;">, phone and fax numbers, IRC nickname

795

and web page

796

<item>password and preferred shell on Debian Project machines

797

</list>

798

799

Most of the information is not accessible to the public, naturally.

800

For more information please read the online documentation that you can find

801

at <url id="&url-debian-db-doc;">.

802

803

Developers can also submit their SSH keys to be used for authorization on the

804

official Debian machines, and even add new *.debian.net DNS entries.

805

Those features are documented at <url id="&url-debian-db-mail-gw;">.

806

807

808

<sect id="archive">The Debian archive

809

810

The &debian-formal; distribution consists of a lot of packages

811

(<file>.deb</file>'s, currently around &number-of-pkgs;) and a few

812

additional files (such as documentation and installation disk images).

813

814

Here is an example directory tree of a complete Debian archive:

815

816

&sample-dist-dirtree;

817

818

As you can see, the top-level directory contains two directories,

819

<file>dists/</file> and <file>pool/</file>. The latter is a “pool” in which the

820

packages actually are, and which is handled by the archive maintenance

821

database and the accompanying programs. The former contains the

822

distributions, stable, testing and unstable.

823

The <file>Packages</file> and <file>Sources</file> files in the

824

distribution subdirectories can reference files in the <file>pool/</file>

825

directory. The directory tree below each of the distributions is arranged

826

in an identical manner. What we describe below for stable is

827

equally applicable to the unstable and testing

828

distributions.

829

830

<file>dists/stable</file> contains three directories, namely <file>main</file>,

831

<file>contrib</file>, and <file>non-free</file>.

832

833

In each of the areas, there is a directory for the source packages

834

(<file>source</file>) and a directory for each supported architecture

835

(<file>binary-i386</file>, <file>binary-m68k</file>, etc.).

836

837

The <file>main</file> area contains additional directories which hold

838

the disk images and some essential pieces of documentation required

839

for installing the Debian distribution on a specific architecture

840

(<file>disks-i386</file>, <file>disks-m68k</file>, etc.).

841

842

843

<sect1 id="archive-sections">Sections

844

845

The main section of the Debian archive is what makes up the

846

official &debian-formal; distribution. The

847

main section is official because it fully complies with all

848

our guidelines. The other two sections do not, to different degrees;

849

as such, they are not officially part of

850

&debian-formal;.

851

852

Every package in the main section must fully comply with the <url

853

id="&url-dfsg;" name="Debian Free Software Guidelines"> (DFSG) and

854

with all other policy requirements as described in the <url

855

id="&url-debian-policy;" name="Debian Policy Manual">. The DFSG is

856

our definition of “free software.” Check out the Debian Policy

857

Manual for details.

858

859

Packages in the contrib section have to comply with the DFSG,

860

but may fail other requirements. For instance, they may depend on

861

non-free packages.

862

863

Packages which do not conform to the DFSG are placed in the

864

non-free section. These packages are not considered as part

865

of the Debian distribution, though we support their use, and we

866

provide infrastructure (such as our bug-tracking system and mailing

867

lists) for non-free software packages.

868

869

The <url id="&url-debian-policy;" name="Debian Policy Manual">

870

contains a more exact definition of the three sections. The above

871

discussion is just an introduction.

872

873

The separation of the three sections at the top-level of the archive

874

is important for all people who want to distribute Debian, either via

875

FTP servers on the Internet or on CD-ROMs: by distributing only the

876

main and contrib sections, one can avoid any legal

877

risks. Some packages in the non-free section do not allow

878

commercial distribution, for example.

879

880

On the other hand, a CD-ROM vendor could easily check the individual

881

package licenses of the packages in non-free and include as

882

many on the CD-ROMs as it's allowed to. (Since this varies greatly from

883

vendor to vendor, this job can't be done by the Debian developers.)

884

885

Note that the term "section" is also used to refer to categories

886

which simplify the organization and browsing of available packages, e.g.

887

admin, net, utils etc. Once upon a time, these

888

sections (subsections, rather) existed in the form of subdirectories within

889

the Debian archive. Nowadays, these exist only in the "Section" header

890

fields of packages.

891

892

893

<sect1>Architectures

894

895

In the first days, the Linux kernel was only available for Intel

896

i386 (or greater) platforms, and so was Debian. But as Linux became

897

more and more popular, the kernel was ported to other architectures,

898

too.

899

900

The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola

901

680x0 (like Atari, Amiga and Macintoshes), MIPS, and PowerPC. The

902

Linux 2.2 kernel supports even more architectures, including ARM and

903

UltraSPARC. Since Linux supports these platforms, Debian decided that

904

it should, too. Therefore, Debian has ports underway; in fact, we

905

also have ports underway to non-Linux kernels. Aside from

906

i386 (our name for Intel x86), there is m68k,

907

alpha, powerpc, sparc, hurd-i386,

908

arm, ia64, hppa, s390, mips,

909

mipsel and sh as of this writing.

910

911

&debian-formal; 1.3 is only available as i386. Debian 2.0

912

shipped for i386 and m68k architectures. Debian 2.1

913

ships for the i386, m68k, alpha, and

914

sparc architectures. Debian 2.2 added support for the

915

powerpc and arm architectures. Debian 3.0 added

916

support of five new architectures: ia64, hppa,

917

s390, mips and mipsel.

918

919

Information for developers and users about the specific ports are

920

available at the <url id="&url-debian-ports;" name="Debian Ports web

921

pages">.

922

923

924

925

<sect1>Packages

926

927

There are two types of Debian packages, namely source and

928

binary packages.

929

930

Source packages consist of either two or three files: a <file>.dsc</file>

931

file, and either a <file>.tar.gz</file> file or both an

932

<file>.orig.tar.gz</file> and a <file>.diff.gz</file> file.

933

934

If a package is developed specially for Debian and is not distributed

935

outside of Debian, there is just one <file>.tar.gz</file> file which

936

contains the sources of the program. If a package is distributed

937

elsewhere too, the <file>.orig.tar.gz</file> file stores the so-called

938

upstream source code, that is the source code that's

939

distributed by the upstream maintainer (often the author of

940

the software). In this case, the <file>.diff.gz</file> contains the

941

changes made by the Debian maintainer.

942

943

The <file>.dsc</file> file lists all the files in the source package together

944

with checksums (<prgn>md5sums</prgn>) and some additional info about

945

the package (maintainer, version, etc.).

946

947

948

<sect1>Distributions

949

950

The directory system described in the previous chapter is itself

951

contained within distribution directories. Each

952

distribution is actually contained in the <file>pool</file> directory in the

953

top-level of the Debian archive itself.

954

955

To summarize, the Debian archive has a root directory within an FTP

956

server. For instance, at the mirror site,

957

<ftpsite>ftp.us.debian.org</ftpsite>, the Debian archive itself is

958

contained in <ftppath>/debian</ftppath>, which is a common location

959

(another is <file>/pub/debian</file>).

960

961

A distribution comprises Debian source and binary packages, and the

962

respective <file>Sources</file> and <file>Packages</file> index files, containing

963

the header information from all those packages. The former are kept in the

964

<file>pool/</file> directory, while the latter are kept in the <file>dists/</file>

965

directory of the archive (for backwards compatibility).

966

967

968

<sect2 id="sec-dists">Stable, testing, and unstable

969

970

There are always distributions called stable (residing in

971

<file>dists/stable</file>), testing (residing in

972

<file>dists/testing</file>), and unstable (residing in

973

<file>dists/unstable</file>). This reflects the development process of the

974

Debian project.

975

976

Active development is done in the unstable distribution

977

(that's why this distribution is sometimes called the development

978

distribution). Every Debian developer can update his or her

979

packages in this distribution at any time. Thus, the contents of this

980

distribution change from day to day. Since no special effort is made

981

to make sure everything in this distribution is working properly, it is

982

sometimes literally unstable.

983

984

The <qref id="testing">"testing"</qref> distribution is generated

985

automatically by taking

986

packages from unstable if they satisfy certain criteria. Those

987

criteria should ensure a good quality for packages within testing.

988

The update to testing is launched each day after the

989

new packages have been installed. See <ref id="testing">.

990

991

After a period of development, once the release manager deems fit, the

992

testing distribution is frozen, meaning that the policies

993

which control how packages move from unstable to testing are

994

tightened. Packages which are too buggy are removed. No changes are

995

allowed into testing except for bug fixes. After some time

996

has elapsed, depending on progress, the testing distribution

997

is frozen even further.

998

Details of the handling of the testing distribution are published

999

by the Release Team on debian-devel-announce.

1000

After the open issues are solved to the satisfaction of the Release Team,

1001

the distribution is released.

1002

Releasing means

1003

that testing is renamed to stable,

1004

and a new copy is created for the new testing,

1005

and the previous stable is renamed to oldstable

1006

and stays there until it is finally archived.

1007

On archiving, the contents are moved to <tt>&archive-host;</tt>).

1008

1009

This development cycle is based on the assumption that the

1010

unstable distribution becomes stable after passing a

1011

period of being in testing. Even once a distribution is

1012

considered stable, a few bugs inevitably remain — that's why the

1013

stable distribution is updated every now and then. However, these

1014

updates are tested very carefully and have to be introduced into the

1015

archive individually to reduce the risk of introducing new bugs. You

1016

can find proposed additions to stable in the

1017

<file>proposed-updates</file> directory. Those packages in

1018

<file>proposed-updates</file> that pass muster are periodically moved as a

1019

batch into the stable distribution and the revision level of the

1020

stable distribution is incremented (e.g., ‘3.0’ becomes

1021

‘3.0r1’, ‘2.2r4’ becomes ‘2.2r5’, and

1022

so forth).

1023

Please refer to

1024

<qref id="upload-stable">uploads to the stable distribution</qref>

1025

for details.

1026

1027

Note that development under unstable continues during the

1028

freeze period, since the unstable distribution remains in

1029

place in parallel with testing.

1030

1031

<sect2>

1032

<heading>More information about the testing distribution</heading>

1033

1034

Packages are usually installed into the `testing' distribution after they

1035

have undergone some degree of testing in unstable.

1036

1037

For more details, please see the <qref id="testing">information about the

1038

testing distribution</qref>.

1039

1040

<sect2 id="experimental">Experimental

1041

1042

The experimental distribution is a special distribution.

1043

It is not a full distribution in the same sense as `stable' and

1044

`unstable' are. Instead, it is meant to be a temporary staging area

1045

for highly experimental software where there's a good chance that the

1046

software could break your system, or software that's just too unstable

1047

even for the unstable distribution (but there is a reason to

1048

package it nevertheless). Users who download and install

1049

packages from experimental are expected to have been duly

1050

warned. In short, all bets are off for the experimental

1051

distribution.

1052

1053

These are the <manref name="sources.list" section="5"> lines for

1054

experimental:

1055

1056

deb http://ftp.<var>xy</var>.debian.org/debian/ experimental main

1057

deb-src http://ftp.<var>xy</var>.debian.org/debian/ experimental main

1058

</example>

1059

1060

If there is a chance that the software could do grave damage to a system,

1061

it is likely to be better to put it into experimental.

1062

For instance, an experimental compressed file system should probably go

1063

into experimental.

1064

1065

Whenever there is a new upstream version of a package that introduces new

1066

features but breaks a lot of old ones, it should either not be uploaded, or

1067

be uploaded to experimental. A new, beta, version of some software

1068

which uses a completely different configuration can go into

1069

experimental, at the maintainer's discretion. If you are working

1070

on an incompatible or complex upgrade situation, you can also use

1071

experimental as a staging area, so that testers can get early

1072

access.

1073

1074

Some experimental software can still go into unstable, with a few

1075

warnings in the description, but that isn't recommended because packages

1076

from unstable are expected to propagate to testing and

1077

thus to stable. You should not be afraid to use

1078

experimental since it does not cause any pain to the ftpmasters,

1079

the experimental packages are automatically removed once you upload

1080

the package in unstable with a higher version number.

1081

1082

New software which isn't likely to damage your system can go directly into

1083

unstable.

1084

1085

An alternative to experimental is to use your personal web space

1086

on <tt>people.debian.org</tt>.

1087

1088

When uploading to unstable a package which had bugs fixed in experimental,

1089

please consider using the option <tt>-v</tt> to <prgn>dpkg-buildpackage</prgn>

1090

to finally get them closed.

1091

1092

<sect1 id="codenames">Release code names

1093

1094

Every released Debian distribution has a code name: Debian

1095

1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0,

1096

`hamm'; Debian 2.1, `slink'; Debian 2.2, `potato'; Debian 3.0, `woody';

1097

Debian 3.1, "sarge";

1098

Debian 4.0, "etch".

1099

There is also a ``pseudo-distribution'', called `sid', which is the current

1100

`unstable' distribution; since packages are moved from `unstable' to

1101

`testing' as they approach stability, `sid' itself is never released.

1102

As well as the usual contents of a Debian distribution, `sid' contains

1103

packages for architectures which are not yet officially supported or

1104

released by Debian. These architectures are planned to be integrated

1105

into the mainstream distribution at some future date.

1106

1107

Since Debian has an open development model (i.e., everyone can

1108

participate and follow the development) even the `unstable' and `testing'

1109

distributions are distributed to the Internet through the Debian FTP and

1110

HTTP server network. Thus, if we had called the directory which contains

1111

the release candidate version `testing', then we would have to rename it

1112

to `stable' when the version is released, which would cause all FTP

1113

mirrors to re-retrieve the whole distribution (which is quite large).

1114

1115

On the other hand, if we called the distribution directories

1116

Debian-x.y from the beginning, people would think that Debian

1117

release x.y is available. (This happened in the past, where a

1118

CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development

1119

version. That's the reason why the first official Debian release was

1120

1.1, and not 1.0.)

1121

1122

Thus, the names of the distribution directories in the archive are

1123

determined by their code names and not their release status (e.g.,

1124

`slink'). These names stay the same during the development period and

1125

after the release; symbolic links, which can be changed easily,

1126

indicate the currently released stable distribution. That's why the

1127

real distribution directories use the code names, while

1128

symbolic links for stable, testing, and

1129

unstable point to the appropriate release directories.

1130

1131

1132

<sect id="mirrors">Debian mirrors

1133

1134

The various download archives and the web site have several mirrors

1135

available in order to relieve our canonical servers from heavy load.

1136

In fact, some of the canonical servers aren't public — a first tier

1137

of mirrors balances the load instead. That way, users always access

1138

the mirrors and get used to using them, which allows Debian to better

1139

spread its bandwidth requirements over several servers and networks,

1140

and basically makes users avoid hammering on one primary location.

1141

Note that the first tier of mirrors is as up-to-date as it can be since

1142

they update when triggered from the internal sites (we call this

1143

"push mirroring").

1144

1145

All the information on Debian mirrors, including a list of the available

1146

public FTP/HTTP servers, can be found at <url id="&url-debian-mirrors;">.

1147

This useful page also includes information and tools which can be helpful if

1148

you are interested in setting up your own mirror, either for internal or

1149

public access.

1150

1151

Note that mirrors are generally run by third-parties who are

1152

interested in helping Debian. As such, developers generally do not

1153

have accounts on these machines.

1154

1155

1156

1157

<heading>The Incoming system

1158

1159

The Incoming system is responsible for collecting updated packages and

1160

installing them in the Debian archive. It consists of a set of

1161

directories and scripts that are installed on <tt>&ftp-master-host;</tt>.

1162

1163

Packages are uploaded by all the maintainers into a directory called

1164

<file>UploadQueue</file>.

1165

This directory is scanned every few minutes by a daemon called

1166

<prgn>queued</prgn>, <file>*.command</file>-files are executed, and

1167

remaining and correctly signed <file>*.changes</file>-files are moved

1168

together with their corresponding files to the <file>unchecked</file>

1169

directory.

1170

This directory is not visible for most Developers, as ftp-master is restricted;

1171

it is scanned every 15 minutes by

1172

the <prgn>katie</prgn> script, which verifies the integrity of the uploaded

1173

packages and their cryptographic signatures.

1174

If the package is considered ready to be installed, it

1175

is moved into the <file>accepted</file> directory. If this is the first upload of

1176

the package (or it has new binary packages),

1177

it is moved to the <file>new</file> directory, where it waits

1178

for approval by the ftpmasters. If the package contains files to be installed

1179

"by hand" it is moved to the <file>byhand</file> directory, where it waits

1180

for manual installation by the ftpmasters. Otherwise, if any error has been detected,

1181

the package is refused and is moved to the <file>reject</file> directory.

1182

1183

Once the package is accepted, the system sends a confirmation

1184

mail to the maintainer and closes all the bugs marked as fixed by the upload,

1185

and the auto-builders may start recompiling it. The package is now publicly

1186

accessible at <url id="&url-incoming;">

1187

until it is really installed

1188

in the Debian archive.

1189

This happens only once a day

1190

(and is also called the `dinstall run' for historical reasons);

1191

the package

1192

is then removed from incoming and installed in the pool along with all

1193

the other packages. Once all the other updates (generating new

1194

<file>Packages</file> and <file>Sources</file> index files for example) have been

1195

made, a special script is called to ask all the primary mirrors to update

1196

themselves.

1197

1198

The archive maintenance software will also send the OpenPGP/GnuPG signed

1199

<file>.changes</file> file that you uploaded to the appropriate mailing

1200

lists. If a package is released with the <tt>Distribution:</tt> set to

1201

`stable', the announcement is sent to &email-debian-changes;.

1202

If a package is released with <tt>Distribution:</tt> set to `unstable'

1203

or `experimental', the announcement will be posted to

1204

&email-debian-devel-changes; instead.

1205

1206

Though ftp-master is restricted, a copy of the installation is available

1207

to all developers on <tt>&ftp-master-mirror;</tt>.

1208

<!-- FIXME: delete it or keep it for historical purposes?

1209

1210

All Debian developers have write access to the <file>unchecked</file>

1211

directory in order to upload their packages; they also have that access

1212

to the <file>reject</file> directory in order to remove their bad uploads

1213

or to move some files back to the <file>unchecked</file> directory. But

1214

all the other directories are only writable by the ftpmasters, which is

1215

why you cannot remove an upload once it has been accepted.

1216

1217

<sect1 id="delayed-incoming-broken">Delayed incoming

1218

1219

Note: This description here is currently not working, because

1220

ftp-master is restricted. Please see <ref id="delayed-incoming"> for

1221

the currently working way.

1222

1223

The <file>unchecked</file> directory has a special <file>DELAYED</file>

1224

subdirectory. It is itself subdivided in nine directories

1225

called <file>1-day</file> to <file>9-day</file>. Packages which are uploaded to

1226

one of those directories will be moved to the real unchecked

1227

directory after the corresponding number of days.

1228

This is done by a script which is run each day and which moves the

1229

packages between the directories. Those which are in "1-day" are

1230

installed in <file>unchecked</file> while the others are moved to the

1231

adjacent directory (for example, a package in <file>5-day</file> will

1232

be moved to <file>4-day</file>). This feature is particularly useful

1233

for people who are doing non-maintainer uploads. Instead of

1234

waiting before uploading a NMU, it is uploaded as soon as it is

1235

ready, but to one of those <file>DELAYED/<var>x</var>-day</file> directories.

1236

That leaves the corresponding number of days for the maintainer

1237

to react and upload another fix themselves if they are not

1238

completely satisfied with the NMU. Alternatively they can remove

1239

the NMU.

1240

1241

The use of that delayed feature can be simplified with a bit

1242

of integration with your upload tool. For instance, if you use

1243

<prgn>dupload</prgn> (see <ref id="dupload">), you can add this

1244

snippet to your configuration file:

1245

1246

$delay = ($ENV{DELAY} || 7);

1247

$cfg{'delayed'} = {

1248

fqdn => "&ftp-master-host;",

1249

login => "yourdebianlogin",

1250

incoming => "/org/ftp.debian.org/incoming/DELAYED/$delay-day/",

1251

dinstall_runs => 1,

1252

method => "scpb"

1253

};

1254

</example>

1255

Once you've made that change, <prgn>dupload</prgn> can be used to

1256

easily upload a package in one of the delayed directories:

1257

<example>DELAY=5 dupload -X-to delayed <changes-file></example>

1258

-->

1259

1260

1261

<sect id="pkg-info">Package information

1262

1263

1264

<sect1 id="pkg-info-web">On the web

1265

1266

Each package has several dedicated web pages.

1267

<tt>http://&packages-host;/<var>package-name</var></tt>

1268

displays each version of the package

1269

available in the various distributions. Each version links to a page

1270

which provides information, including the package description,

1271

the dependencies, and package download links.

1272

1273

The bug tracking system tracks bugs for each package.

1274

You can view the bugs of a given package at the URL

1275

<tt>http://&bugs-host;/<var>package-name</var></tt>.

1276

1277

<sect1 id="madison">The <prgn>madison</prgn> utility

1278

1279

<prgn>madison</prgn> is a command-line utility that is available

1280

on <tt>&ftp-master-host;</tt>, and on

1281

the mirror on <tt>&ftp-master-mirror;</tt>. It

1282

uses a single argument corresponding to a package name. In result

1283

it displays which version of the package is available for each

1284

architecture and distribution combination. An example will explain

1285

it better.

1286

1287

1288

$ madison libdbd-mysql-perl

1289

libdbd-mysql-perl | 1.2202-4 | stable | source, alpha, arm, i386, m68k, powerpc, sparc

1290

libdbd-mysql-perl | 1.2216-2 | testing | source, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc

1291

libdbd-mysql-perl | 1.2216-2.0.1 | testing | alpha

1292

libdbd-mysql-perl | 1.2219-1 | unstable | source, alpha, arm, hppa, i386, ia64, m68k, mips, mipsel, powerpc, s390, sparc

1293

</example>

1294

1295

In this example, you can see that the version in unstable differs from

1296

the version in testing and that there has been a binary-only NMU of the

1297

package for the alpha architecture. Each version of the package has been

1298

recompiled on most of the architectures.

1299

1300

<sect id="pkg-tracking-system">The Package Tracking System

1301

1302

The Package Tracking System (PTS) is an email-based tool to track

1303

the activity of a source package. This really means that you can

1304

get the same emails that the package maintainer gets, simply by

1305

subscribing to the package in the PTS.

1306

1307

Each email sent through the PTS is classified under one of

1308

the keywords listed below. This will let you select the mails that

1309

you want to receive.

1310

1311

By default you will get:

1312

1313

1314

<item>

1315

All the bug reports and following discussions.

1316

1317

<tag><tt>bts-control</tt>

1318

<item>

1319

The email notifications from <email>control@bugs.debian.org</email>

1320

about bug report status changes.

1321

1322

<tag><tt>upload-source</tt>

1323

<item>

1324

The email notification from <prgn>katie</prgn> when an uploaded source

1325

package is accepted.

1326

1327

<tag><tt>katie-other</tt>

1328

<item>

1329

Other warning and error emails from <prgn>katie</prgn> (such as an

1330

override disparity for the section and/or the priority field).

1331

1332

<tag><tt>default</tt>

1333

<item>

1334

Any non-automatic email sent to the PTS by people who wanted to

1335

contact the subscribers of the package. This can be done by sending mail

1336

to <tt><var>sourcepackage</var>@&pts-host;</tt>. In order to prevent spam,

1337

all messages sent to these addresses must contain the <tt>X-PTS-Approved</tt>

1338

header with a non-empty value.

1339

1340

<tag><tt>summary</tt>

1341

<item>

1342

Regular summary emails about the package's status.

1343

Currently, only progression in testing is sent.

1344

1345

</taglist>

1346

1347

1348

You can also decide to receive additional information:

1349

1350

<tag><tt>upload-binary</tt>

1351

<item>

1352

The email notification from <prgn>katie</prgn> when an uploaded binary

1353

package is accepted. In other words, whenever a build daemon or a porter

1354

uploads your package for another architecture, you can get an email to

1355

track how your package gets recompiled for all architectures.

1356

1357

1358

<item>

1359

CVS commit notifications, if the package has a CVS repository and the

1360

maintainer has set up forwarding commit notifications to the PTS.

1361

1362

1363

<item>

1364

Translations of descriptions or debconf templates

1365

submitted to the Debian Description Translation Project.

1366

1367

<tag><tt>derivatives</tt>

1368

<item>

1369

Information about changes made to the package in derivative distributions

1370

(for example Ubuntu).

1371

</taglist>

1372

1373

<sect1 id="pts-commands">The PTS email interface

1374

1375

You can control your subscription(s) to the PTS by sending

1376

various commands to <email>pts@qa.debian.org</email>.

1377

1378

1379

1380

<tag><tt>subscribe <sourcepackage> [<email>]</tt>

1381

<item>

1382

Subscribes <var>email</var> to communications related to the source package

1383

<var>sourcepackage</var>. Sender address is used if the second argument is

1384

not present. If <var>sourcepackage</var> is not a valid source package,

1385

you'll get a warning. However if it's a valid binary package, the PTS

1386

will subscribe you to the corresponding source package.

1387

1388

<tag><tt>unsubscribe <sourcepackage> [<email>]</tt>

1389

<item>

1390

Removes a previous subscription to the source package <var>sourcepackage</var>

1391

using the specified email address or the sender address if the second

1392

argument is left out.

1393

1394

<tag><tt>unsubscribeall [<email>]</tt>

1395

<item>

1396

Removes all subscriptions of the specified email address or the sender

1397

address if the second argument is left out.

1398

1399

<tag><tt>which [<email>]</tt>

1400

<item>

1401

Lists all subscriptions for the sender or the email address optionally

1402

specified.

1403

1404

<tag><tt>keyword [<email>]</tt>

1405

<item>

1406

Tells you the keywords that you are accepting.

1407

For an explanation of keywords, <qref id="pkg-tracking-system">see

1408

above</qref>. Here's a quick summary:

1409

<list>

1410

<item><tt>bts</tt>: mails coming from the Debian Bug Tracking System

1411

<item><tt>bts-control</tt>: reply to mails sent to &email-bts-control;

1412

<item><tt>summary</tt>: automatic summary mails about the state of a package

1413

<item><tt>cvs</tt>: notification of CVS commits

1414

<item><tt>ddtp</tt>: translations of descriptions and debconf templates

1415

<item><tt>derivatives</tt>: changes made on the package by derivative distributions

1416

<item><tt>upload-source</tt>: announce of a new source upload that

1417

has been accepted

1418

<item><tt>upload-binary</tt>: announce of a new binary-only upload (porting)

1419

<item><tt>katie-other</tt>: other mails from ftpmasters

1420

(override disparity, etc.)

1421

<item><tt>default</tt>: all the other mails (those which aren't "automatic")

1422

</list>

1423

1424

<tag><tt>keyword <sourcepackage> [<email>]</tt>

1425

<item>

1426

Same as the previous item but for the given source package, since

1427

you may select a different set of keywords for each source package.

1428

1429

<tag><tt>keyword [<email>] {+|-|=} <list of keywords></tt>

1430

<item>

1431

Accept (+) or refuse (-) mails classified under the given keyword(s).

1432

Define the list (=) of accepted keywords. This changes the default set

1433

of keywords accepted by a user.

1434

1435

<tag><tt>keywordall [<email>] {+|-|=} <list of keywords></tt>

1436

<item>

1437

Accept (+) or refuse (-) mails classified under the given keyword(s).

1438

Define the list (=) of accepted keywords. This changes the set of

1439

accepted keywords of all the currently active subscriptions of a user.

1440

1441

<tag><tt>keyword <sourcepackage> [<email>] {+|-|=} <list of keywords></tt>

1442

<item>

1443

Same as previous item but overrides the keywords list for the

1444

indicated source package.

1445

1446

<tag><tt>quit | thanks | --</tt>

1447

<item>

1448

Stops processing commands. All following lines are ignored by

1449

the bot.

1450

</taglist>

1451

1452

1453

The <prgn>pts-subscribe</prgn> command-line utility (from the

1454

<package>devscripts</package> package) can be handy to temporarily

1455

subscribe to some packages, for example after having made an

1456

non-maintainer upload.

1457

1458

<sect1 id="pts-mail-filtering">Filtering PTS mails

1459

1460

Once you are subscribed to a package, you will get the mails sent to

1461

<tt><var>sourcepackage</var>@packages.qa.debian.org</tt>. Those mails

1462

have special headers appended to let you filter them in a special

1463

mailbox (e.g. with <prgn>procmail</prgn>). The added headers are

1464

<tt>X-Loop</tt>, <tt>X-PTS-Package</tt>, <tt>X-PTS-Keyword</tt> and

1465

<tt>X-Unsubscribe</tt>.

1466

1467

Here is an example of added headers for a source upload notification

1468

on the <package>dpkg</package> package:

1469

1470

X-Loop: dpkg@&pts-host;

1471

X-PTS-Package: dpkg

1472

X-PTS-Keyword: upload-source

1473

X-Unsubscribe: echo 'unsubscribe dpkg' | mail pts@qa.debian.org

1474

</example>

1475

1476

<sect1 id="pts-cvs-commit">Forwarding CVS commits in the PTS

1477

1478

If you use a publicly accessible CVS repository for maintaining

1479

your Debian package, you may want to forward the commit notification

1480

to the PTS so that the subscribers (and possible co-maintainers) can

1481

closely follow the package's evolution.

1482

1483

Once you set up the CVS repository to generate commit notifications,

1484

you just have to make sure it sends a copy of those mails

1485

to <tt><var>sourcepackage</var>_cvs@&pts-host;</tt>. Only the people

1486

who accept the cvs keyword will receive these notifications.

1487

1488

<sect1 id="pts-web">The PTS web interface

1489

1490

The PTS has a web interface at <url id="http://&pts-host;/"> that puts

1491

together a lot of information about each source package. It features many useful

1492

links (BTS, QA stats, contact information, DDTP translation status,

1493

buildd logs) and gathers much more information from various places

1494

(30 latest changelog entries, testing status, ...). It's a very useful

1495

tool if you want to know what's going on with a specific source

1496

package. Furthermore there's a form that allows easy subscription to

1497

the PTS via email.

1498

1499

You can jump directly to the web page concerning a specific source package

1500

with a URL like <tt>http://&pts-host;/<var>sourcepackage</var></tt>.

1501

1502

This web interface has been designed like a portal for the development of

1503

packages: you can add custom content on your packages' pages. You can

1504

add "static information" (news items that are meant to stay available

1505

indefinitely) and news items in the "latest news" section.

1506

1507

Static news items can be used to indicate:

1508

<list>

1509

<item>the availability of a project hosted on <qref id="alioth">Alioth</qref> for co-maintaining the package

1510

<item>a link to the upstream web site

1511

<item>a link to the upstream bug tracker

1512

<item>the existence of an IRC channel dedicated to the software

1513

<item>any other available resource that could be useful in the maintenance of the package

1514

</list>

1515

Usual news items may be used to announce that:

1516

<list>

1517

<item>beta packages are available for testing

1518

<item>final packages are expected for next week

1519

<item>the packaging is about to be redone from scratch

1520

<item>backports are available

1521

<item>the maintainer is on vacation (if they wish to publish this information)

1522

<item>a NMU is being worked on

1523

<item>something important will affect the package

1524

</list>

1525

1526

Both kinds of news are generated in a similar manner: you just have to send

1527

an email either to <email>pts-static-news@qa.debian.org</email> or to

1528

<email>pts-news@qa.debian.org</email>. The mail should indicate which

1529

package is concerned by having the name of the source package in a

1530

<tt>X-PTS-Package</tt> mail header or in a <tt>Package</tt> pseudo-header (like the

1531

BTS reports). If a URL is available in the <tt>X-PTS-Url</tt> mail header or in

1532

the <tt>Url</tt> pseudo-header, then the result is a link to that URL instead

1533

of a complete news item.

1534

1535

Here are a few examples of valid mails used to generate news items in

1536

the PTS. The first one adds a link to the cvsweb interface of debian-cd

1537

in the "Static information" section:

1538

1539

From: Raphael Hertzog <hertzog@debian.org>

1540

To: pts-static-news@qa.debian.org

1541

Subject: Browse debian-cd CVS repository with cvsweb

1542

1543

Package: debian-cd

1544

Url: http://cvs.debian.org/debian-cd/

1545

</example>

1546

1547

The second one is an announcement sent to a mailing list which is also sent

1548

to the PTS so that it is published on the PTS web page of the package. Note the

1549

use of the BCC field to avoid answers sent to the PTS by mistake.

1550

1551

From: Raphael Hertzog <hertzog@debian.org>

1552

To: debian-gtk-gnome@lists.debian.org

1553

Bcc: pts-news@qa.debian.org

1554

Subject: Galeon 2.0 backported for woody

1555

X-PTS-Package: galeon

1556

1557

Hello gnomers!

1558

1559

I'm glad to announce that galeon has been backported for woody. You'll find

1560

everything here:

1561

...

1562

</example>

1563

1564

Think twice before adding a news item to the PTS because you won't be able

1565

to remove it later and you won't be able to edit it either. The only thing

1566

that you can do is send a second news item that will deprecate the

1567

information contained in the previous one.

1568

1569

<sect id="ddpo">Developer's packages overview

1570

1571

A QA (quality assurance) web portal is available at <url

1572

id="&url-ddpo;"> which displays a table listing all the packages

1573

of a single developer (including those where the party is listed as

1574

a co-maintainer). The table gives a good summary about the developer's

1575

packages: number of bugs by severity, list of available versions in each

1576

distribution, testing status and much more including links to any other

1577

useful information.

1578

1579

It is a good idea to look up your own data regularly so that

1580

you don't forget any open bugs, and so that you don't forget which

1581

packages are your responsibility.

1582

1583

<sect id="alioth">Debian *Forge: Alioth

1584

1585

Alioth is a fairly new Debian service, based on a slightly modified version

1586

of the GForge software (which evolved from SourceForge). This software

1587

offers developers access to easy-to-use tools such as bug trackers, patch

1588

manager, project/task managers, file hosting services, mailing lists, CVS

1589

repositories etc. All these tools are managed via a web interface.

1590

1591

It is intended to provide facilities to free software projects backed or led

1592

by Debian, facilitate contributions from external developers to projects

1593

started by Debian, and help projects whose goals are the promotion of Debian

1594

or its derivatives.

1595

1596

All Debian developers automatically have an account on Alioth.

1597

They can activate it by using the recover password facility.

1598

External developers can request guest accounts on Alioth.

1599

1600

For more information please visit <url id="&url-alioth;">.

1601

1602

<sect id="developer-misc">Goodies for Developers

1603

1604

<sect1 id="lwn">LWN Subscriptions

1605

1606

Since October of 2002, HP has sponsored a subscription to LWN for all

1607

interested Debian developers.

1608

1609

Details on how to get access to this benefit are in

1610

<url id="http://lists.debian.org/debian-devel-announce/2002/10/msg00018.html">.

1611

1612

1613

1614

<chapt id="pkgs">Managing Packages

1615

1616

This chapter contains information related to creating, uploading,

1617

maintaining, and porting packages.

1618

1619

1620

<sect id="newpackage">New packages

1621

1622

If you want to create a new package for the Debian distribution, you

1623

should first check the <url id="&url-wnpp;" name="Work-Needing and

1624

Prospective Packages (WNPP)"> list. Checking the WNPP list ensures that

1625

no one is already working on packaging that software, and that effort is

1626

not duplicated. Read the <url id="&url-wnpp;" name="WNPP web pages"> for

1627

more information.

1628

1629

Assuming no one else is already working on your prospective package,

1630

you must then submit a bug report (<ref id="submit-bug">) against the

1631

pseudo-package <package>wnpp</package>

1632

describing your plan to create a new package, including, but not

1633

limiting yourself to, a description of the package, the license of the

1634

prospective package, and the current URL where it can be downloaded

1635

from.

1636

1637

You should set the subject of the bug to ``ITP: <var>foo</var>

1638

package for <var>foo</var>. The severity of the bug report must be set

1639

to wishlist. If you feel it's necessary, send a copy to

1640

&email-debian-devel; by putting the address in the <tt>X-Debbugs-CC:</tt> header

1641

of the message (no, don't use <tt>CC:</tt>, because that way the message's subject

1642

won't indicate the bug number).

1643

1644

Please include a <tt>Closes: bug#<var>nnnnn</var></tt> entry in the

1645

changelog of the new package in order for the bug report to be

1646

automatically closed once the new package is installed in the archive

1647

(see <ref id="upload-bugfix">).

1648

1649

When closing security bugs include CVE numbers as well as the

1650

"Closes: #nnnnn".

1651

This is useful for the security team to track vulnerabilities.

1652

If an upload is made to fix the bug before the advisory ID is known,

1653

it is encouraged to modify the historical changelog entry with the next upload.

1654

Even in this case, please include all available pointers to background

1655

information in the original changelog entry.

1656

1657

1658

There are a number of reasons why we ask maintainers to announce their

1659

intentions:

1660

1661

<item>

1662

It helps the (potentially new) maintainer to tap into the experience

1663

of people on the list, and lets them know if anyone else is working

1664

on it already.

1665

<item>

1666

It lets other people thinking about working on the package know that

1667

there already is a volunteer, so efforts may be shared.

1668

<item>

1669

It lets the rest of the maintainers know more about the package than

1670

the one line description and the usual changelog entry ``Initial release''

1671

that gets posted to <tt>debian-devel-changes</tt>.

1672

<item>

1673

It is helpful to the people who live off unstable (and form our first

1674

line of testers). We should encourage these people.

1675

<item>

1676

The announcements give maintainers and other interested parties a

1677

better feel of what is going on, and what is new, in the project.

1678

</list>

1679

1680

Please see <url id="http://ftp-master.debian.org/REJECT-FAQ.html">

1681

for common rejection reasons for a new package.

1682

1683

<sect id="changelog-entries">Recording changes in the package

1684

1685

Changes that you make to the package need to be recorded in the

1686

<file>debian/changelog</file>. These changes should provide a concise

1687

description of what was changed, why (if it's in doubt), and note if

1688

any bugs were closed. They also record when the package was

1689

completed. This file will be installed in

1690

<file>/usr/share/doc/<var>package</var>/changelog.Debian.gz</file>, or

1691

<file>/usr/share/doc/<var>package</var>/changelog.gz</file> for native

1692

packages.

1693

1694

The <file>debian/changelog</file> file conforms to a certain structure,

1695

with a number of different fields. One field of note, the

1696

distribution, is described in <ref id="distribution">. More

1697

information about the structure of this file can be found in

1698

the Debian Policy section titled "<file>debian/changelog</file>".

1699

1700

Changelog entries can be used to automatically close Debian bugs when

1701

the package is installed into the archive. See <ref

1702

id="upload-bugfix">.

1703

1704

It is conventional that the changelog entry of a package that

1705

contains a new upstream version of the software looks like this:

1706

1707

* new upstream version

1708

</example>

1709

1710

There are tools to help you create entries and finalize the

1711

<file>changelog</file> for release — see <ref id="devscripts">

1712

and <ref id="dpkg-dev-el">.

1713

1714

See also <ref id="bpp-debian-changelog">.

1715

1716

1717

<sect id="sanitycheck">Testing the package

1718

1719

Before you upload your package, you should do basic testing on it. At

1720

a minimum, you should try the following activities (you'll need to

1721

have an older version of the same Debian package around):

1722

<list>

1723

<item>

1724

Install the package and make sure the software works, or upgrade the

1725

package from an older version to your new version if a Debian package

1726

for it already exists.

1727

<item>

1728

Run <prgn>lintian</prgn> over the package. You can run

1729

<prgn>lintian</prgn> as follows: <tt>lintian -v

1730

<var>package-version</var>.changes</tt>. This will check the source

1731

package as well as the binary package. If you don't understand the

1732

output that <prgn>lintian</prgn> generates, try adding the <tt>-i</tt>

1733

switch, which will cause <prgn>lintian</prgn> to output a very verbose

1734

description of the problem.

1735

1736

Normally, a package should not be uploaded if it causes lintian

1737

to emit errors (they will start with <tt>E</tt>).

1738

1739

For more information on <prgn>lintian</prgn>, see <ref id="lintian">.

1740

<item>

1741

Optionally run <ref id="debdiff"> to analyze changes from an older version,

1742

if one exists.

1743

<item>

1744

Downgrade the package to the previous version (if one exists) — this

1745

tests the <file>postrm</file> and <file>prerm</file> scripts.

1746

<item>

1747

Remove the package, then reinstall it.

1748

<item>

1749

Copy the source package in a different directory and try unpacking it and

1750

rebuilding it. This tests if the package relies on existing files outside of

1751

it, or if it relies on permissions being preserved on the files shipped inside

1752

the .diff.gz file.

1753

</list>

1754

1755

1756

<sect id="sourcelayout">Layout of the source package

1757

1758

There are two types of Debian source packages:

1759

<list>

1760

<item>the so-called native packages, where there is no

1761

distinction between the original sources and the patches

1762

applied for Debian

1763

<item>the (more common) packages where there's an original source

1764

tarball file accompanied by another file that contains the

1765

patches applied for Debian

1766

</list>

1767

1768

For the native packages, the source package includes a Debian source control

1769

file (<tt>.dsc</tt>) and the source tarball (<tt>.tar.gz</tt>). A source

1770

package of a non-native package includes a Debian source control file, the

1771

original source tarball (<tt>.orig.tar.gz</tt>) and the Debian patches

1772

(<tt>.diff.gz</tt>).

1773

1774

Whether a package is native or not is determined when it is built by

1775

<manref name="dpkg-buildpackage" section="1">. The rest of this section

1776

relates only to non-native packages.

1777

1778

The first time a version is uploaded which corresponds to a particular

1779

upstream version, the original source tar file should be uploaded and

1780

included in the <file>.changes</file> file. Subsequently, this very same

1781

tar file should be used to build the new diffs and <file>.dsc</file>

1782

files, and will not need to be re-uploaded.

1783

1784

By default, <prgn>dpkg-genchanges</prgn> and

1785

<prgn>dpkg-buildpackage</prgn> will include the original source tar

1786

file if and only if the Debian revision part of the source version

1787

number is 0 or 1, indicating a new upstream version. This behavior

1788

may be modified by using <tt>-sa</tt> to always include it or

1789

<tt>-sd</tt> to always leave it out.

1790

1791

If no original source is included in the upload, the original

1792

source tar-file used by <prgn>dpkg-source</prgn> when constructing the

1793

<file>.dsc</file> file and diff to be uploaded must be

1794

byte-for-byte identical with the one already in the archive.

1795

1796

Please notice that, in non-native packages, permissions on files that are not

1797

present in the .orig.tar.gz will not be preserved, as diff does not store file

1798

permissions in the patch.

1799

1800

1801

<sect id="distribution">Picking a distribution

1802

1803

Each upload needs to specify which distribution the package is intended

1804

for. The package build process extracts this information from the first

1805

line of the <file>debian/changelog</file> file and places it in the

1806

<tt>Distribution</tt> field of the <tt>.changes</tt> file.

1807

1808

There are several possible values for this field: `stable', `unstable',

1809

`testing-proposed-updates' and `experimental'. Normally, packages are

1810

uploaded into unstable.

1811

1812

Actually, there are two other possible distributions: `stable-security' and

1813

`testing-security', but read <ref id="bug-security"> for more information on

1814

those.

1815

1816

It is not possible to upload a package into several distributions

1817

at the same time.

1818

1819

1820

<heading>Special case: uploads to the stable distribution</heading>

1821

1822

Uploading to stable means that the package will be placed into the

1823

<file>stable-proposed-updates</file> directory of the Debian archive for further

1824

testing before it is actually included in stable.

1825

1826

Extra care should be taken when uploading to stable. Basically, a

1827

package should only be uploaded to stable if one of the following happens:

1828

<list>

1829

<item>a truly critical functionality problem

1830

<item>the package becomes uninstallable

1831

<item>a released architecture lacks the package

1832

</list>

1833

1834

In the past, uploads to stable were used to address security

1835

problems as well. However, this practice is deprecated, as uploads

1836

used for Debian security advisories are automatically copied to the

1837

appropriate <file>proposed-updates</file> archive when the advisory is

1838

released. See <ref id="bug-security"> for detailed information on

1839

handling security problems.

1840

1841

Changing anything else in the package that isn't important is discouraged,

1842

because even trivial fixes can cause bugs later on.

1843

1844

Packages uploaded to stable need to be compiled on systems running

1845

stable, so that their dependencies are limited to the libraries

1846

(and other packages) available in stable; for example, a package

1847

uploaded to stable that depends on a library package that only

1848

exists in unstable will be rejected. Making changes to dependencies of other

1849

packages (by messing with <tt>Provides</tt> or shlibs files), possibly making

1850

those other packages uninstallable, is strongly discouraged.

1851

1852

The Release Team (which can be reached at &email-debian-release;) will

1853

regularly evaluate the uploads in stable-proposed-updates and decide if

1854

your package can be included in stable. Please be clear (and

1855

verbose, if necessary) in your changelog entries for uploads to

1856

stable, because otherwise the package won't be considered for

1857

inclusion.

1858

1859

It's best practice to speak with the stable release manager before

1860

uploading to stable/stable-proposed-updates, so that the

1861

uploaded package fits the needs of the next point release.

1862

1863

1864

<heading>Special case: uploads to testing/testing-proposed-updates</heading>

1865

1866

Please see the information in the <qref id="t-p-u">testing section</qref> for details.

1867

1868

1869

<sect id="upload">Uploading a package

1870

1871

<sect1 id="upload-ftp-master">Uploading to <tt>ftp-master</tt>

1872

1873

To upload a package, you should upload the files (including the signed

1874

changes and dsc-file) with anonymous ftp to

1875

<ftpsite>&ftp-master-host;</ftpsite> in the directory &upload-queue;.

1876

To get the files processed there, they need to be signed with a key in the

1877

debian keyring.

1878

1879

Please note that you should transfer

1880

the changes file last. Otherwise, your upload may be rejected because the

1881

archive maintenance software will parse the changes file and see that not

1882

all files have been uploaded.

1883

1884

You may also find the Debian packages <ref id="dupload"> or

1885

<ref id="dput"> useful

1886

when uploading packages. These handy programs help automate the

1887

process of uploading packages into Debian.

1888

1889

For removing packages, please see the README file in that ftp directory,

1890

and the Debian package <ref id="dcut">.

1891

1892

<sect1 id="upload-non-us">Uploading to <tt>non-US</tt>

1893

1894

Note: non-us was discontinued with the release of sarge.

1895

1896

1897

<sect1 id="delayed-incoming">Delayed uploads

1898

1899

Delayed uploads are done for the moment via the delayed queue at

1900

gluck. The upload-directory is

1901

<ftpsite>gluck:~tfheen/DELAYED/[012345678]-day</ftpsite>.

1902

0-day is uploaded multiple times per day to ftp-master.

1903

1904

With a fairly recent dput, this section

1905

1906

[tfheen_delayed]

1907

method = scp

1908

fqdn = gluck.debian.org

1909

incoming = ~tfheen

1910

</example>

1911

in ~/.dput.cf should work fine for uploading to the DELAYED queue.

1912

1913

Note:

1914

Since this upload queue goes to <tt>ftp-master</tt>, the

1915

prescription found in <ref id="upload-ftp-master"> applies here as well.

1916

1917

<sect1>Security uploads

1918

1919

Do NOT upload a package to the security upload queue

1920

(oldstable-security,

1921

stable-security, etc.) without prior authorization from the security

1922

team. If the package does not exactly meet the team's requirements, it

1923

will cause many problems and delays in dealing with the unwanted upload.

1924

For details, please see section <ref id="bug-security">.

1925

1926

<sect1>Other upload queues

1927

1928

The scp queues on ftp-master, and security are mostly unusable

1929

due to the login restrictions on those hosts.

1930

1931

The anonymous queues on ftp.uni-erlangen.de and ftp.uk.debian.org are

1932

currently down. Work is underway to resurrect them.

1933

1934

The queues on master.debian.org, samosa.debian.org, master.debian.or.jp,

1935

and ftp.chiark.greenend.org.uk are down permanently, and will not be

1936

resurrected. The queue in Japan will be replaced with a new queue on

1937

hp.debian.or.jp some day.

1938

1939

For the time being, the anonymous ftp queue on auric.debian.org (the

1940

former ftp-master) works, but it is deprecated and will be removed at

1941

some point in the future.

1942

1943

1944

<heading>Notification that a new package has been installed</heading>

1945

1946

The Debian archive maintainers are responsible for handling package

1947

uploads. For the most part, uploads are automatically handled on a

1948

daily basis by the archive maintenance tools, <prgn>katie</prgn>.

1949

Specifically, updates to existing packages to

1950

the `unstable' distribution are handled automatically. In other cases,

1951

notably new packages, placing the uploaded package into the

1952

distribution is handled manually. When uploads are handled manually,

1953

the change to the archive may take up to a month to occur. Please be

1954

patient.

1955

1956

In any case, you will receive an email notification indicating that the

1957

package has been added to the archive, which also indicates which bugs will

1958

be closed by the upload. Please examine this notification carefully,

1959

checking if any bugs you meant to close didn't get triggered.

1960

1961

The installation notification also includes information on what

1962

section the package was inserted into. If there is a disparity, you

1963

will receive a separate email notifying you of that. Read on below.

1964

1965

Note that if you upload via queues, the queue daemon software will

1966

also send you a notification by email.

1967

1968

<sect id="override-file">Specifying the package section, subsection and priority

1969

1970

The <file>debian/control</file> file's <tt>Section</tt> and

1971

<tt>Priority</tt> fields do not actually specify where the file will

1972

be placed in the archive, nor its priority. In order to retain the

1973

overall integrity of the archive, it is the archive maintainers who

1974

have control over these fields. The values in the

1975

<file>debian/control</file> file are actually just hints.

1976

1977

The archive maintainers keep track of the canonical sections and

1978

priorities for packages in the override file. If there is a

1979

disparity between the override file and the package's fields

1980

as indicated in <file>debian/control</file>, then you will receive an

1981

email noting the divergence when the package is installed into the

1982

archive. You can either correct your <file>debian/control</file> file

1983

for your next upload, or else you may wish to make a change in the

1984

override file.

1985

1986

To alter the actual section that a package is put in, you need to

1987

first make sure that the <file>debian/control</file> file in your package

1988

is accurate. Next, send an email &email-override; or submit a bug

1989

against <package>ftp.debian.org</package> requesting that the section

1990

or priority for your package be changed from the old section or

1991

priority to the new one. Be sure to explain your reasoning.

1992

1993

For more information about override files, see <manref

1994

name="dpkg-scanpackages" section="1"> and

1995

<url id="&url-bts-devel;#maintincorrect">.

1996

1997

Note that the <tt>Section</tt> field describes both the section as

1998

well as the subsection, which are described in <ref

1999

id="archive-sections">. If the section is "main", it should be

2000

omitted. The list of allowable subsections can be found in <url

2001

id="&url-debian-policy;ch-archive.html#s-subsections">.

2002

2003

2004

<sect id="bug-handling">Handling bugs

2005

2006

Every developer has to be able to work with the Debian <url name="bug

2007

tracking system" id="&url-bts;">. This includes knowing how to file bug

2008

reports properly (see <ref id="submit-bug">), how to update them and

2009

reorder them, and how to process and close them.

2010

2011

The bug tracking system's features are described

2012

in the <url id="&url-bts-devel;" name="BTS documentation for developers">.

2013

This includes closing bugs, sending followup messages, assigning severities

2014

and tags, marking bugs as forwarded, and other issues.

2015

2016

Operations such as reassigning bugs to other packages, merging separate

2017

bug reports about the same issue, or reopening bugs when they are

2018

prematurely closed, are handled using the so-called control mail server.

2019

All of the commands available on this server are described in the

2020

<url id="&url-bts-control;" name="BTS control server documentation">.

2021

2022

<sect1 id="bug-monitoring">Monitoring bugs

2023

2024

If you want to be a good maintainer, you should periodically check the

2025

<url id="&url-bts;" name="Debian bug tracking system (BTS)"> for your

2026

packages. The BTS contains all the open bugs against your packages.

2027

You can check them by browsing this page:

2028

<tt>http://&bugs-host;/<var>yourlogin</var>@debian.org</tt>.

2029

2030

Maintainers interact with the BTS via email addresses at

2031

<tt>&bugs-host;</tt>. Documentation on available commands can be

2032

found at <url id="&url-bts;">, or, if you have installed the

2033

<package>doc-debian</package> package, you can look at the local files

2034

&file-bts-docs;.

2035

2036

Some find it useful to get periodic reports on open bugs. You can add

2037

a cron job such as the following if you want to get a weekly email

2038

outlining all the open bugs against your packages:

2039

2040

# ask for weekly reports of bugs in my packages

2041

&cron-bug-report;

2042

</example>

2043

Replace <var>address</var> with your official Debian

2044

maintainer address.

2045

2046

<sect1 id="bug-answering">Responding to bugs

2047

2048

When responding to bugs, make sure that any discussion you have about

2049

bugs is sent both to the original submitter of the bug, and to the bug

2050

itself (e.g., <email>123@&bugs-host;</email>). If you're writing a new

2051

mail and you don't remember the submitter email address, you can

2052

use the <email>123-submitter@&bugs-host;</email> email to

2053

contact the submitter and to record your mail within the

2054

bug log (that means you don't need to send a copy of the mail to

2055

<email>123@&bugs-host;</email>).

2056

2057

If you get a bug which mentions "FTBFS", this means "Fails to build

2058

from source". Porters frequently use this acronym.

2059

2060

Once you've dealt with a bug report (e.g. fixed it), mark it as

2061

done (close it) by sending an explanation message to

2062

<email>123-done@&bugs-host;</email>. If you're fixing a bug by

2063

changing and uploading the package, you can automate bug closing as

2064

described in <ref id="upload-bugfix">.

2065

2066

You should never close bugs via the bug server <tt>close</tt>

2067

command sent to &email-bts-control;. If you do so, the original

2068

submitter will not receive any information about why the bug was

2069

closed.

2070

2071

<sect1 id="bug-housekeeping">Bug housekeeping

2072

2073

As a package maintainer, you will often find bugs in other packages or

2074

have bugs reported against your packages which are actually bugs in

2075

other packages. The bug tracking system's features

2076

are described in the <url id="&url-bts-devel;" name="BTS documentation for

2077

Debian developers">. Operations such as reassigning, merging, and tagging

2078

bug reports are described in the <url id="&url-bts-control;" name="BTS

2079

control server documentation">. This section contains

2080

some guidelines for managing your own bugs, based on the collective

2081

Debian developer experience.

2082

2083

Filing bugs for problems that you find in other packages is one of

2084

the "civic obligations" of maintainership, see <ref id="submit-bug">

2085

for details. However, handling the bugs in your own packages is

2086

even more important.

2087

2088

Here's a list of steps that you may follow to handle a bug report:

2089

2090

<item>

2091

Decide whether the report corresponds to a real bug or not. Sometimes

2092

users are just calling a program in the wrong way because they haven't

2093

read the documentation. If you diagnose this, just close the bug with

2094

enough information to let the user correct their problem (give pointers

2095

to the good documentation and so on). If the same report comes up

2096

again and again you may ask yourself if the documentation is good

2097

enough or if the program shouldn't detect its misuse in order to

2098

give an informative error message. This is an issue that may need

2099

to be brought up with the upstream author.

2100

2101

If the bug submitter disagrees with your decision to close the bug,

2102

they may reopen it until you find an agreement on how to handle it.

2103

If you don't find any, you may want to tag the bug <tt>wontfix</tt>

2104

to let people know that the bug exists but that it won't be corrected.

2105

If this situation is unacceptable, you (or the submitter) may want to

2106

require a decision of the technical committee by reassigning the bug

2107

to <package>tech-ctte</package> (you may use the clone command of

2108

the BTS if you wish to keep it reported against your package). Before

2109

doing so, please read the <url id="&url-tech-ctte;" name="recommended procedure">.

2110

<item>

2111

If the bug is real but it's caused by another package, just reassign

2112

the bug to the right package. If you don't know which package it should

2113

be reassigned to, you should ask for help on

2114

<qref id="irc-channels">IRC</qref> or on &email-debian-devel;.

2115

Please make sure that the maintainer(s) of the package

2116

the bug is reassigned to

2117

know why you reassigned it.

2118

2119

Sometimes you also have to adjust the severity of the bug so that it

2120

matches our definition of the severity. That's because people tend to

2121

inflate the severity of bugs to make sure their bugs are fixed quickly.

2122

Some bugs may even be dropped to wishlist severity when the requested

2123

change is just cosmetic.

2124

<item>

2125

If the bug is real but the same problem has already been reported by

2126

someone else, then the two relevant bug reports should be merged

2127

into one using the merge command of the BTS.

2128

In this way, when the

2129

bug is fixed, all of the submitters will be informed of this.

2130

(Note, however, that emails sent to one bug report's submitter won't

2131

automatically be sent to the other report's submitter.)

2132

For more

2133

details on the technicalities of the merge command and its relative,

2134

the unmerge command, see the BTS control server documentation.

2135

<item>

2136

The bug submitter may have forgotten to provide some information, in which

2137

case you have to ask them for the required information. You may use the

2138

<tt>moreinfo</tt> tag to mark the bug as such. Moreover if you can't

2139

reproduce the bug, you tag it <tt>unreproducible</tt>. Anyone who

2140

can reproduce the bug is then invited to provide more information

2141

on how to reproduce it. After a few months, if this information has not

2142

been sent by someone, the bug may be closed.

2143

<item>

2144

If the bug is related to the packaging, you just fix it. If you are not

2145

able to fix it yourself, then tag the bug as <tt>help</tt>. You can

2146

also ask for help on &email-debian-devel; or &email-debian-qa;. If it's an

2147

upstream problem, you have to forward it to the upstream author.

2148

Forwarding a bug is not enough, you have to check at each release if

2149

the bug has been fixed or not. If it has, you just close it, otherwise

2150

you have to remind the author about it. If you have the required skills

2151

you can prepare a patch that fixes the bug and

2152

send it to the author at the same time.

2153

Make sure to send the patch to the BTS and to

2154

tag the bug as <tt>patch</tt>.

2155

<item>

2156

If you have fixed a bug in your local copy, or if a fix has been

2157

committed to the CVS repository, you may tag the bug as

2158

<tt>pending</tt> to let people know that the bug is corrected and that

2159

it will be closed with the next upload (add the <tt>closes:</tt> in

2160

the <file>changelog</file>). This is particularly useful if you

2161

are several developers working on the same package.

2162

<item>

2163

Once a corrected package is available in the unstable

2164

distribution, you can close the bug. This can be done automatically,

2165

read <ref id="upload-bugfix">.

2166

</enumlist>

2167

2168

<sect1 id="upload-bugfix">When bugs are closed by new uploads

2169

2170

As bugs and problems are fixed in your packages, it is your

2171

responsibility as the package maintainer to close these bugs. However,

2172

you should not close a bug until the package which fixes the bug has

2173

been accepted into the Debian archive. Therefore, once you get

2174

notification that your updated package has been installed into the

2175

archive, you can and should close the bug in the BTS.

2176

Also, the bug should be closed with the correct version.

2177

2178

However, it's possible to avoid having to manually close bugs after the

2179

upload — just list the fixed bugs in your <file>debian/changelog</file>

2180

file, following a certain syntax, and the archive maintenance software

2181

will close the bugs for you. For example:

2182

2183

2184

acme-cannon (3.1415) unstable; urgency=low

2185

2186

* Frobbed with options (closes: Bug#98339)

2187

* Added safety to prevent operator dismemberment, closes: bug#98765,

2188

bug#98713, #98714.

2189

* Added man page. Closes: #98725.

2190

</example>

2191

2192

Technically speaking, the following Perl regular expression describes

2193

how bug closing changelogs are identified:

2194

2195

/closes:\s*(?:bug)?\#\s*\d+(?:,\s*(?:bug)?\#\s*\d+)*/ig

2196

</example>

2197

2198

We prefer the <tt>closes: #<var>XXX</var></tt> syntax, as it is the

2199

most concise entry and the easiest to integrate with the text of the

2200

<file>changelog</file>.

2201

Unless specified different by the <var>-v</var>-switch to

2202

<prgn>dpkg-buildpackage</prgn>, only the bugs closed in the

2203

most recent changelog entry are closed (basically, exactly

2204

the bugs mentioned in the changelog-part

2205

in the <file>.changes</file> file are closed).

2206

2207

Historically, uploads identified as

2208

<qref id="nmu">Non-maintainer upload (NMU)</qref>

2209

were tagged <tt>fixed</tt> instead of being closed,

2210

but that practice was ceased with the advent of version-tracking.

2211

The same applied to the tag <tt>fixed-in-experimental</tt>.

2212

2213

If you happen to mistype a bug number or forget a bug in the changelog

2214

entries, don't hesitate to undo any damage the error caused. To reopen

2215

wrongly closed bugs, send a <tt>reopen <var>XXX</var></tt> command to

2216

the bug tracking system's control address, &email-bts-control;. To

2217

close any remaining bugs that were fixed by your upload, email the

2218

<file>.changes</file> file to <email>XXX-done@&bugs-host;</email>,

2219

where <var>XXX</var> is the bug number, and

2220

put "Version: YYY" and an empty line as the first two lines

2221

of the body of the email,

2222

where <var>YYY</var> is the first version

2223

where the bug has been fixed.

2224

2225

2226

Bear in mind that it is not obligatory to close bugs using the

2227

changelog as described above. If you simply want to close bugs that

2228

don't have anything to do with an upload you made, do it by emailing

2229

an explanation to <email>XXX-done@&bugs-host;</email>. Do

2230

not close bugs in the changelog entry of a version if

2231

the changes in that version of the package don't have any bearing on

2232

the bug.

2233

2234

For general information on how to write your changelog entries, see

2235

<ref id="bpp-debian-changelog">.

2236

2237

2238

<sect1 id="bug-security">Handling security-related bugs

2239

2240

Due to their sensitive nature, security-related bugs must be handled

2241

carefully. The Debian Security Team exists to coordinate this

2242

activity, keeping track of outstanding security problems, helping

2243

maintainers with security problems or fixing them themselves, sending

2244

security advisories, and maintaining security.debian.org.

2245

2246

2247

2248

2249

2250

When you become aware of a security-related bug in a Debian package,

2251

whether or not you are the maintainer, collect pertinent information

2252

about the problem, and promptly contact the security team at

2253

&email-security-team; as soon as possible. DO NOT UPLOAD any

2254

packages for stable; the security team will do that.

2255

2256

Useful information includes, for example:

2257

2258

2259

<item>Which versions of the package are known to be affected by the

2260

bug. Check each version that is present in a supported Debian

2261

release, as well as testing and unstable.

2262

2263

<item>The nature of the fix, if any is available (patches are

2264

especially helpful)

2265

2266

<item>Any fixed packages that you have prepared yourself (send only

2267

the <tt>.diff.gz</tt> and <tt>.dsc</tt> files and read <ref

2268

id="bug-security-building"> first)

2269

2270

<item>Any assistance you can provide to help with testing (exploits,

2271

regression testing, etc.)

2272

2273

<item>Any information needed for the advisory (see <ref

2274

id="bug-security-advisories">)

2275

2276

</list>

2277

2278

<sect2 id="bug-security-confidentiality">Confidentiality

2279

2280

Unlike most other activities within Debian, information about security

2281

issues must sometimes be kept private for a time.

2282

This allows software distributors to coordinate their disclosure in

2283

order to minimize their users' exposure. Whether this is the

2284

case depends on the nature of the problem and corresponding fix, and

2285

whether it is already a matter of public knowledge.

2286

2287

2288

There are several ways developers can learn of a security problem:

2289

2290

2291

<item>they notice it on a public forum (mailing list, web site, etc.)

2292

<item>someone files a bug report

2293

<item>someone informs them via private email

2294

</list>

2295

2296

In the first two cases, the information is public and it is important

2297

to have a fix as soon as possible. In the last case, however, it

2298

might not be public information. In that case there are a few

2299

possible options for dealing with the problem:

2300

2301

<list>

2302

<item>If the security exposure is minor, there is sometimes no need

2303

to keep the problem a secret and a fix should be made and released.

2304

2305

<item>If the problem is severe, it is preferable to share the

2306

information with

2307

other vendors and coordinate a release. The security team keeps

2308

in contact with the various organizations and individuals and can take

2309

care of that.

2310

</list>

2311

2312

2313

In all cases if the person who reports the problem asks that it not

2314

be disclosed, such requests should be honored, with the obvious

2315

exception of informing the security team in order that a fix may be

2316

produced for a stable release of Debian. When sending confidential

2317

information to the security team, be sure to mention this fact.

2318

2319

2320

Please note that if secrecy is needed you may not upload a fix to

2321

unstable (or anywhere else, such as a public CVS repository). It is

2322

not sufficient to obfuscate the details of the change, as the code

2323

itself is public, and can (and will) be examined by the general public.

2324

2325

2326

There are two reasons for releasing information even though secrecy is

2327

requested: the problem has been known for a while, or the problem

2328

or exploit has become public.

2329

2330

<sect2 id="bug-security-advisories">Security Advisories

2331

2332

Security advisories are only issued for the current, released stable

2333

distribution, and not for testing or unstable. When released,

2334

advisories

2335

are sent to the &email-debian-security-announce;

2336

2337

mailing list and posted on <url

2338

id="&url-debian-security-advisories;" name="the security web page">.

2339

Security advisories are written and posted by the security

2340

team. However they certainly do not mind if a

2341

maintainer can supply some of the information for them, or write part

2342

of the text. Information that should be in an advisory includes:

2343

2344

2345

<item>A description of the problem and its scope, including:

2346

<list>

2347

<item>The type of problem (privilege escalation, denial of

2348

service, etc.)

2349

<item>What privileges may be gained, and by whom (if any)

2350

<item>How it can be exploited

2351

<item>Whether it is remotely or locally exploitable

2352

<item>How the problem was fixed

2353

</list>

2354

2355

This information allows users to assess the threat to their systems.

2356

2357

<item>Version numbers of affected packages

2358

<item>Version numbers of fixed packages

2359

<item>Information on where to obtain the updated packages

2360

(usually from the Debian security archive)

2361

<item>References to upstream advisories, <url

2362

id="http://cve.mitre.org" name="CVE"> identifiers, and any other

2363

information useful in cross-referencing the vulnerability

2364

</list>

2365

2366

2367

<heading>Preparing packages to address security issues</heading>

2368

2369

One way that you can assist the security team in their duties is to

2370

provide them with fixed packages suitable for a security advisory for

2371

the stable

2372

Debian release.

2373

2374

When an update is made to the stable release, care must be taken to

2375

avoid changing system behavior or introducing new bugs. In order to

2376

do this, make as few changes as possible to fix the bug. Users and

2377

administrators rely on the exact behavior of a release once it is

2378

made, so any change that is made might break someone's system. This

2379

is especially true of libraries: make sure you never change the API or

2380

ABI, no matter how small the change.

2381

2382

This means that moving to a new upstream version is not a good

2383

solution. Instead, the relevant changes should be back-ported to the

2384

version present in the current stable Debian release. Generally,

2385

upstream maintainers are willing to help if needed. If not, the

2386

Debian security team may be able to help.

2387

2388

In some cases, it is not possible to back-port a security fix, for

2389

example when large amounts of source code need to be modified or

2390

rewritten. If this happens, it may be necessary to move to a new

2391

upstream version. However, this is only done in extreme situations,

2392

and you must always coordinate that with the security team beforehand.

2393

2394

Related to this is another important guideline: always test your

2395

changes. If you have an exploit available, try it and see if it

2396

indeed succeeds on the unpatched package and fails on the fixed

2397

package. Test other, normal actions as well, as sometimes a security

2398

fix can break seemingly unrelated features in subtle ways.

2399

2400

Do NOT include any changes in your package which are

2401

not directly related to fixing the vulnerability. These will only

2402

need to be reverted, and this wastes time. If there are other bugs in

2403

your package that you would like to fix, make an upload to

2404

proposed-updates in the usual way, after the security advisory is

2405

issued. The security update mechanism is not a means for introducing

2406

changes to your package which would otherwise be rejected from the

2407

stable release, so please do not attempt to do this.

2408

2409

Review and test your changes as much as possible. Check the

2410

differences from the previous version repeatedly

2411

(<prgn>interdiff</prgn> from the <package>patchutils</package> package

2412

and <prgn>debdiff</prgn> from <package>devscripts</package> are useful

2413

tools for this, see <ref id="debdiff">).

2414

2415

Be sure to verify the following items:

2416

2417

<list>

2418

<item>Target the right distribution in your

2419

<file>debian/changelog</file>. For stable this is <tt>stable-security</tt> and for

2420

testing this is <tt>testing-security</tt>, and for the previous

2421

stable release, this is <tt>oldstable-security</tt>. Do not target

2422

<var>distribution</var>-proposed-updates or <tt>stable</tt>!

2423

2424

<item>The upload should have urgency=high.

2425

2426

<item>Make descriptive, meaningful changelog entries. Others will

2427

rely on them to determine whether a particular bug was fixed.

2428

Always include an external reference, preferably a CVE

2429

identifier, so that it can be cross-referenced. Include the same

2430

information in the changelog for unstable, so that it is clear that

2431

the same bug was fixed, as this is very helpful when verifying

2432

that the bug is fixed in the next stable release. If a CVE

2433

identifier has not yet been assigned, the security team will

2434

request one so that it can be included in the package and in the advisory.

2435

2436

<item>Make sure the version number is proper. It must be greater

2437

than the current package, but less than package versions in later

2438

distributions. If in doubt, test it with <tt>dpkg

2439

--compare-versions</tt>. Be careful not to re-use a version

2440

number that you have already used for a previous upload. For

2441

testing, there must be

2442

a higher version in unstable. If there is none yet (for example,

2443

if testing and unstable have the same version) you must upload a

2444

new version to unstable first.

2445

2446

<item>Do not make source-only uploads if your package has any

2447

binary-all packages (do not use the <tt>-S</tt> option to

2448

<prgn>dpkg-buildpackage</prgn>). The <prgn>buildd</prgn> infrastructure will

2449

not build those. This point applies to normal package uploads as

2450

well.

2451

2452

<item>Unless the upstream source has been uploaded to

2453

security.debian.org before (by a previous security update), build

2454

the upload with full upstream source (<tt>dpkg-buildpackage

2455

-sa</tt>). If there has been a previous upload to

2456

security.debian.org with the same upstream version, you may upload

2457

without upstream source (<tt>dpkg-buildpackage -sd</tt>).

2458

2459

<item>Be sure to use the exact same <file>*.orig.tar.gz</file> as used in the

2460

normal archive, otherwise it is not possible to move the security

2461

fix into the main archives later.

2462

2463

<item>Build the package on a clean

2464

system which only has packages installed from the distribution you

2465

are building for. If you do not have such a system yourself, you

2466

can use a debian.org machine (see <ref id="server-machines">)

2467

or setup a chroot (see <ref id="pbuilder"> and

2468

<ref id="debootstrap">).

2469

</list>

2470

2471

<sect2 id="bug-security-upload">Uploading the fixed package

2472

2473

Do NOT upload a package to the security upload queue

2474

(oldstable-security, stable-security, etc.) without

2475

prior authorization from the security team. If the package does not

2476

exactly meet the team's requirements, it will cause many problems and

2477

delays in dealing with the unwanted upload.

2478

2479

Do NOT upload your fix to proposed-updates without

2480

coordinating with the security team. Packages from

2481

security.debian.org will be copied into the proposed-updates directory

2482

automatically. If a package with the same or a higher version number

2483

is already installed into the archive, the security update will be

2484

rejected by the archive system. That way, the stable distribution

2485

will end up without a security update for this package instead.

2486

2487

Once you have created and tested the new package and it has been

2488

approved by the security team, it needs to be uploaded so that it can

2489

be installed in the archives. For security uploads, the place to

2490

upload to is

2491

<tt>ftp://security-master.debian.org/pub/SecurityUploadQueue/</tt> .

2492

2493

2494

Once an upload to the security queue has been accepted, the package

2495

will automatically be rebuilt for all architectures and stored for

2496

verification by the security team.

2497

2498

2499

Uploads which are waiting for acceptance or verification are only

2500

accessible by the security team. This is necessary since there might

2501

be fixes for security problems that cannot be disclosed yet.

2502

2503

2504

If a member of the security team accepts a package, it will be

2505

installed on security.debian.org as well as proposed for the proper

2506

<var>distribution</var>-proposed-updates on ftp-master.

2507

2508

2509

<heading>Moving, removing, renaming, adopting, and orphaning

2510

packages</heading>

2511

2512

Some archive manipulation operations are not automated in the Debian

2513

upload process. These procedures should be manually followed by

2514

maintainers. This chapter gives guidelines on what to do in these

2515

cases.

2516

2517

<sect1 id="moving-pkgs">Moving packages

2518

2519

Sometimes a package will change its section. For instance, a

2520

package from the `non-free' section might be GPL'd in a later version,

2521

in which case the package should be moved to `main' or

2522

`contrib'.<footnote> See the <url id="&url-debian-policy;"

2523

name="Debian Policy Manual"> for guidelines on what section a package

2524

belongs in.

2525

</footnote>

2526

2527

If you need to change the section for one of your packages, change the

2528

package control information to place the package in the desired

2529

section, and re-upload the package (see the <url id="&url-debian-policy;"

2530

name="Debian Policy Manual"> for details).

2531

You must ensure that you include the <file>.orig.tar.gz</file> in your upload

2532

(even if you are not uploading a new upstream version),

2533

or it will not appear in the new section together with the rest of the package.

2534

If your new section is

2535

valid, it will be moved automatically. If it does not, then contact

2536

the ftpmasters in order to understand what happened.

2537

2538

If, on the other hand, you need to change the subsection of

2539

one of your packages (e.g., ``devel'', ``admin''), the procedure is

2540

slightly different. Correct the subsection as found in the control

2541

file of the package, and re-upload that. Also, you'll need to get the

2542

override file updated, as described in <ref id="override-file">.

2543

2544

2545

<sect1 id="removing-pkgs">Removing packages

2546

2547

If for some reason you want to completely remove a package (say, if it

2548

is an old compatibility library which is no longer required), you

2549

need to file a bug against <tt>ftp.debian.org</tt> asking that the

2550

package be removed;

2551

as all bugs, this bug should normally have normal severity.

2552

Make sure you indicate which distribution the

2553

package should be removed from. Normally, you can only have packages

2554

removed from unstable and experimental. Packages

2555

are not removed from testing directly. Rather, they will be

2556

removed automatically after the package has been removed from

2557

unstable and no package in testing depends on it.

2558

2559

There is one exception when an explicit removal request is not necessary:

2560

If a (source or binary) package is an orphan, it will be removed

2561

semi-automatically.

2562

For a binary-package, this means if there is no longer any source package

2563

producing this binary package;

2564

if the binary package is just no longer produced on some architectures,

2565

a removal request is still necessary.

2566

For a source-package, this means that all binary packages it refers to

2567

have been taken over by another source package.

2568

2569

In your removal request, you have to detail the reasons justifying the request.

2570

This is to

2571

avoid unwanted removals and to keep a trace of why a package has been

2572

removed. For example, you can provide the name of the package that

2573

supersedes the one to be removed.

2574

2575

Usually you only ask for the removal of a package maintained by yourself.

2576

If you want to remove another package, you have to get the approval

2577

of its maintainer.

2578

2579

If in doubt concerning whether a package is disposable, email

2580

&email-debian-devel; asking for opinions. Also of interest is the

2581

<prgn>apt-cache</prgn> program from the <package>apt</package>

2582

package. When invoked as <tt>apt-cache showpkg

2583

<var>package</var></tt>, the program will show details for

2584

<var>package</var>, including reverse depends.

2585

Other useful programs include

2586

<tt>apt-cache rdepends</tt>,

2587

<prgn>apt-rdepends</prgn> and

2588

<prgn>grep-dctrl</prgn>.

2589

Removal of orphaned packages is discussed on &email-debian-qa;.

2590

2591

Once the package has been removed, the package's bugs should be handled.

2592

They should either be reassigned to another package in the case where

2593

the actual code has evolved into another package (e.g. <tt>libfoo12</tt>

2594

was removed because <tt>libfoo13</tt> supersedes it) or closed if the

2595

software is simply no longer part of Debian.

2596

2597

<sect2>Removing packages from <file>Incoming</file>

2598

2599

In the past, it was possible to remove packages from <file>incoming</file>.

2600

However, with the introduction of the new incoming system, this is no longer

2601

possible. Instead, you have to upload a new revision of your package with

2602

a higher version than the package you want to replace. Both versions will be

2603

installed in the archive but only the higher version will actually be

2604

available in unstable since the previous version will immediately

2605

be replaced by the higher. However, if you do proper testing of your

2606

packages, the need to replace a package should not occur too often anyway.

2607

2608

<sect1>Replacing or renaming packages

2609

2610

When you make a mistake naming your package, you should follow a two-step

2611

process to rename it. First, set

2612

your <file>debian/control</file> file to replace and conflict with the

2613

obsolete name of the package (see the <url id="&url-debian-policy;"

2614

name="Debian Policy Manual"> for details). Once you've uploaded

2615

the package and the package has moved into the archive, file a bug

2616

against <tt>ftp.debian.org</tt> asking to remove the package with the

2617

obsolete name. Do not forget to properly reassign the package's bugs

2618

at the same time.

2619

2620

At other times, you may make a mistake in constructing your package and

2621

wish to replace it. The only way to do this is to increase the version

2622

number and upload a new version. The old version will be expired in

2623

the usual manner. Note that this applies to each part of your package,

2624

including the sources: if you wish to replace the upstream source tarball

2625

of your package, you will need to upload it with a different version. An

2626

easy possibility is to replace <file>foo_1.00.orig.tar.gz</file> with

2627

<file>foo_1.00+0.orig.tar.gz</file>. This restriction gives each file

2628

on the ftp site a unique name, which helps to ensure consistency across the

2629

mirror network.

2630

2631

<sect1 id="orphaning">Orphaning a package

2632

2633

If you can no longer maintain a package, you need to inform others,

2634

and see that the package is marked as orphaned.

2635

You should set the package maintainer to <tt>Debian QA Group

2636

&orphan-address;</tt> and submit a bug report

2637

against the pseudo package <package>wnpp</package>. The bug report should be

2638

titled <tt>O: <var>package</var> -- <var>short description</var></tt>

2639

indicating that the package is now orphaned. The severity of the bug

2640

should be set to normal; if the package has a priority of standard

2641

or higher, it should be set to important.

2642

If you feel it's necessary, send a copy

2643

to &email-debian-devel; by putting the address in the X-Debbugs-CC: header

2644

of the message (no, don't use CC:, because that way the message's subject

2645

won't indicate the bug number).

2646

2647

If you just intend to give the package away, but you can keep maintainership

2648

for the moment, then you should instead submit

2649

a bug against <package>wnpp</package> and title it <tt>RFA: <var>package</var> --

2650

<var>short description</var></tt>.

2651

<tt>RFA</tt> stands for Request For Adoption.

2652

2653

More information is on the <url id="&url-wnpp;" name="WNPP web pages">.

2654

2655

<sect1 id="adopting">Adopting a package

2656

2657

A list of packages in need of a new maintainer is available in the

2658

<url name="Work-Needing and Prospective Packages list (WNPP)"

2659

id="&url-wnpp;">. If you wish to take over maintenance of any of the

2660

packages listed in the WNPP, please take a look at the aforementioned

2661

page for information and procedures.

2662

2663

It is not OK to simply take over a package that you feel is neglected

2664

— that would be package hijacking. You can, of course, contact the

2665

current maintainer and ask them if you may take over the package.

2666

If you have reason to believe a maintainer has gone AWOL

2667

(absent without leave), see <ref id="mia-qa">.

2668

2669

Generally, you may not take over the package without the assent of the

2670

current maintainer. Even if they ignore you, that is still not grounds to

2671

take over a package. Complaints about maintainers should be brought up on

2672

the developers' mailing list. If the discussion doesn't end with a positive

2673

conclusion, and the issue is of a technical nature, consider bringing it to

2674

the attention of the technical committee (see the <url name="technical

2675

committee web page" id="&url-tech-ctte;"> for more information).

2676

2677

If you take over an old package, you probably want to be listed as the

2678

package's official maintainer in the bug system. This will happen

2679

automatically once you upload a new version with an updated

2680

<tt>Maintainer:</tt> field, although it can take a few hours after the

2681

upload is done. If you do not expect to upload a new version for a while,

2682

you can use <ref id="pkg-tracking-system"> to get the bug reports. However,

2683

make sure that the old maintainer has no problem with the fact that

2684

they will continue to receive the bugs during that time.

2685

2686

2687

<sect id="porting">Porting and being ported

2688

2689

Debian supports an ever-increasing number of architectures. Even if

2690

you are not a porter, and you don't use any architecture but one, it

2691

is part of your duty as a maintainer to be aware of issues of

2692

portability. Therefore, even if you are not a porter, you should read

2693

most of this chapter.

2694

2695

Porting is the act of building Debian packages for architectures that

2696

are different from the original architecture of the package

2697

maintainer's binary package. It is a unique and essential activity.

2698

In fact, porters do most of the actual compiling of Debian packages.

2699

For instance, for a single i386 binary package, there must be

2700

a recompile for each architecture, which amounts to

2701

&number-of-arches; more builds.

2702

2703

2704

<sect1 id="kind-to-porters">Being kind to porters

2705

2706

Porters have a difficult and unique task, since they are required to

2707

deal with a large volume of packages. Ideally, every source package

2708

should build right out of the box. Unfortunately, this is often not

2709

the case. This section contains a checklist of ``gotchas'' often

2710

committed by Debian maintainers — common problems which often stymie

2711

porters, and make their jobs unnecessarily difficult.

2712

2713

The first and most important thing is to respond quickly to bug or

2714

issues raised by porters. Please treat porters with courtesy, as if

2715

they were in fact co-maintainers of your package (which, in a way, they

2716

are). Please be tolerant of succinct or even unclear bug reports;

2717

do your best to hunt down whatever the problem is.

2718

2719

By far, most of the problems encountered by porters are caused by

2720

packaging bugs in the source packages. Here is a checklist

2721

of things you should check or be aware of.

2722

2723

2724

<item>

2725

Make sure that your <tt>Build-Depends</tt> and

2726

<tt>Build-Depends-Indep</tt> settings in <file>debian/control</file>

2727

are set properly. The best way to validate this is to use the

2728

<package>debootstrap</package> package to create an unstable chroot

2729

environment (see <ref id="debootstrap">).

2730

Within that chrooted environment, install the

2731

<package>build-essential</package> package and any package

2732

dependencies mentioned in <tt>Build-Depends</tt> and/or

2733

<tt>Build-Depends-Indep</tt>. Finally, try building your package

2734

within that chrooted environment. These steps can be automated

2735

by the use of the <prgn>pbuilder</prgn> program which is provided by

2736

the package of the same name (see <ref id="pbuilder">).

2737

2738

If you can't set up a proper chroot, <prgn>dpkg-depcheck</prgn> may be

2739

of assistance (see <ref id="dpkg-depcheck">).

2740

2741

See the <url id="&url-debian-policy;" name="Debian Policy

2742

Manual"> for instructions on setting build dependencies.

2743

<item>

2744

Don't set architecture to a value other than ``all'' or ``any'' unless

2745

you really mean it. In too many cases, maintainers don't follow the

2746

instructions in the <url id="&url-debian-policy;" name="Debian Policy

2747

Manual">. Setting your architecture to ``i386'' is usually incorrect.

2748

<item>

2749

Make sure your source package is correct. Do <tt>dpkg-source -x

2750

<var>package</var>.dsc</tt> to make sure your source package unpacks

2751

properly. Then, in there, try building your package from scratch with

2752

<prgn>dpkg-buildpackage</prgn>.

2753

<item>

2754

Make sure you don't ship your source package with the

2755

<file>debian/files</file> or <file>debian/substvars</file> files.

2756

They should be removed by the `clean' target of

2757

<file>debian/rules</file>.

2758

<item>

2759

Make sure you don't rely on locally installed or hacked configurations

2760

or programs. For instance, you should never be calling programs in

2761

<file>/usr/local/bin</file> or the like. Try not to rely on programs

2762

being setup in a special way. Try building your package on another

2763

machine, even if it's the same architecture.

2764

<item>

2765

Don't depend on the package you're building being installed already (a

2766

sub-case of the above issue).

2767

<item>

2768

Don't rely on the compiler being a certain version, if possible. If

2769

not, then make sure your build dependencies reflect the restrictions,

2770

although you are probably asking for trouble, since different

2771

architectures sometimes standardize on different compilers.

2772

<item>

2773

Make sure your debian/rules contains separate ``binary-arch'' and

2774

``binary-indep'' targets, as the Debian Policy Manual requires.

2775

Make sure that both targets work independently, that is, that you can

2776

call the target without having called the other before. To test this,

2777

try to run <tt>dpkg-buildpackage -B</tt>.

2778

</enumlist>

2779

2780

2781

<sect1 id="porter-guidelines">Guidelines for porter uploads

2782

2783

If the package builds out of the box for the architecture to be ported

2784

to, you are in luck and your job is easy. This section applies to

2785

that case; it describes how to build and upload your binary package so

2786

that it is properly installed into the archive. If you do have to

2787

patch the package in order to get it to compile for the other

2788

architecture, you are actually doing a source NMU, so consult <ref

2789

id="nmu-guidelines"> instead.

2790

2791

For a porter upload, no changes are being made to the source. You do

2792

not need to touch any of the files in the source package. This

2793

includes <file>debian/changelog</file>.

2794

2795

The way to invoke <prgn>dpkg-buildpackage</prgn> is as

2796

<tt>dpkg-buildpackage -B -m<var>porter-email</var></tt>. Of course,

2797

set <var>porter-email</var> to your email address. This will do a

2798

binary-only build of only the architecture-dependent portions of the

2799

package, using the `binary-arch' target in <file>debian/rules</file>.

2800

2801

If you are working on a Debian machine for your porting efforts and you

2802

need to sign your upload locally for its acceptance in the archive, you

2803

can run <prgn>debsign</prgn> on your <file>.changes</file> file to have

2804

it signed conveniently, or use the remote signing mode of <prgn>dpkg-sig</prgn>.

2805

2806

2807

2808

<heading>Recompilation or binary-only NMU</heading>

2809

2810

Sometimes the initial porter upload is problematic because the environment

2811

in which the package was built was not good enough (outdated or obsolete

2812

library, bad compiler, ...). Then you may just need to recompile it in

2813

an updated environment. However, you have to bump the version number in

2814

this case, so that the old bad package can be replaced in the Debian archive

2815

(<prgn>katie</prgn> refuses to install new packages if they don't have a

2816

version number greater than the currently available one).

2817

2818

You have to make sure that your binary-only NMU doesn't render the package

2819

uninstallable. This could happen when a source package generates

2820

arch-dependent and arch-independent packages that depend on each other via

2821

$(Source-Version).

2822

2823

Despite the

2824

required modification of the changelog, these are called binary-only NMUs

2825

— there is no need in this case to trigger all other architectures

2826

to consider themselves out of date or requiring recompilation.

2827

2828

Such recompilations require special ``magic'' version numbering, so that

2829

the archive maintenance tools recognize that, even though there is a

2830

new Debian version, there is no corresponding source update. If you

2831

get this wrong, the archive maintainers will reject your upload (due

2832

to lack of corresponding source code).

2833

2834

The ``magic'' for a recompilation-only NMU is triggered by using a

2835

suffix appended to the package version number,

2836

following the form b<number>.

2837

For instance, if the latest version you are

2838

recompiling against was version ``2.9-3'', your NMU should carry a

2839

version of ``2.9-3+b1''. If the latest version was ``3.4+b1'' (i.e, a

2840

native package with a previous recompilation NMU), your NMU should have

2841

a version number of ``3.4+b2''.

2842

2843

2844

In the past, such NMUs used the third-level number on the Debian part of

2845

the revision to denote their recompilation-only status; however, this

2846

syntax was ambiguous with native packages and did not allow proper

2847

ordering of recompile-only NMUs, source NMUs, and security NMUs on the

2848

same package, and has therefore been abandoned in favor of this new

2849

syntax.</footnote>

2850

2851

Similar to initial porter uploads, the correct way of invoking

2852

<prgn>dpkg-buildpackage</prgn> is <tt>dpkg-buildpackage -B</tt> to only

2853

build the architecture-dependent parts of the package.

2854

2855

2856

2857

<heading>When to do a source NMU if you are a porter</heading>

2858

2859

Porters doing a source NMU generally follow the guidelines found in

2860

<ref id="nmu">, just like non-porters. However, it is expected that

2861

the wait cycle for a porter's source NMU is smaller than for a

2862

non-porter, since porters have to cope with a large quantity of

2863

packages.

2864

Again, the situation varies depending on the distribution they are

2865

uploading to. It also varies whether the architecture is a candidate

2866

for inclusion into the next stable release; the release managers

2867

decide and announce which architectures are candidates.

2868

2869

If you are a porter doing an NMU for `unstable', the above

2870

guidelines for porting should be followed, with two variations.

2871

Firstly, the acceptable waiting period — the time between when the

2872

bug is submitted to the BTS and when it is OK to do an NMU — is seven

2873

days for porters working on the unstable distribution. This period

2874

can be shortened if the problem is critical and imposes hardship on

2875

the porting effort, at the discretion of the porter group. (Remember,

2876

none of this is Policy, just mutually agreed upon guidelines.)

2877

For uploads to stable or testing, please coordinate with the appropriate

2878

release team first.

2879

2880

Secondly, porters doing source NMUs should make sure that the bug they

2881

submit to the BTS should be of severity `serious' or greater. This

2882

ensures that a single source package can be used to compile every

2883

supported Debian architecture by release time. It is very important

2884

that we have one version of the binary and source package for all

2885

architecture in order to comply with many licenses.

2886

2887

Porters should try to avoid patches which simply kludge around bugs in

2888

the current version of the compile environment, kernel, or libc.

2889

Sometimes such kludges can't be helped. If you have to kludge around

2890

compiler bugs and the like, make sure you <tt>#ifdef</tt> your work

2891

properly; also, document your kludge so that people know to remove it

2892

once the external problems have been fixed.

2893

2894

Porters may also have an unofficial location where they can put the

2895

results of their work during the waiting period. This helps others

2896

running the port have the benefit of the porter's work, even during

2897

the waiting period. Of course, such locations have no official

2898

blessing or status, so buyer beware.

2899

2900

2901

2902

<heading>Porting infrastructure and automation</heading>

2903

2904

There is infrastructure and several tools to help automate package

2905

porting. This section contains a brief overview of this automation and

2906

porting to these tools; see the package documentation or references for

2907

full information.

2908

2909

<sect2>

2910

<heading>Mailing lists and web pages</heading>

2911

2912

Web pages containing the status of each port can be found at <url

2913

id="&url-debian-ports;">.

2914

2915

Each port of Debian has a mailing list. The list of porting mailing

2916

lists can be found at <url id="&url-debian-port-lists;">. These lists

2917

are used to coordinate porters, and to connect the users of a given

2918

port with the porters.

2919

</sect2>

2920

2921

<sect2>

2922

<heading>Porter tools</heading>

2923

2924

Descriptions of several porting tools can be found in <ref

2925

id="tools-porting">.

2926

</sect2>

2927

2928

2929

<heading><package>buildd</package></heading>

2930

2931

The <package>buildd</package> system is used as a distributed,

2932

client-server build distribution system. It is usually used in

2933

conjunction with auto-builders, which are ``slave'' hosts

2934

which simply check out and attempt to auto-build packages which need

2935

to be ported. There is also an email interface to the system, which

2936

allows porters to ``check out'' a source package (usually one which

2937

cannot yet be auto-built) and work on it.

2938

2939

<package>buildd</package> is not yet available as a package; however,

2940

most porting efforts are either using it currently or planning to use

2941

it in the near future. The actual automated builder is packaged as

2942

<package>sbuild</package>, see its description in <ref id="sbuild">.

2943

The complete <package>buildd</package> system also collects a number of as yet unpackaged

2944

components which are currently very useful and in use continually,

2945

such as <prgn>andrea</prgn> and

2946

<prgn>wanna-build</prgn>.

2947

2948

Some of the data produced by <package>buildd</package> which is

2949

generally useful to porters is available on the web at <url

2950

id="&url-buildd;">. This data includes nightly updated information

2951

from <prgn>andrea</prgn> (source dependencies) and

2952

<package>quinn-diff</package> (packages needing recompilation).

2953

2954

We are quite proud of this system, since it has so

2955

many possible uses. Independent development groups can use the system for

2956

different sub-flavors of Debian, which may or may not really be of

2957

general interest (for instance, a flavor of Debian built with <prgn>gcc</prgn>

2958

bounds checking). It will also enable Debian to recompile entire

2959

distributions quickly.

2960

2961

The buildds admins of each arch can be contacted at the mail address

2962

$arch@buildd.debian.org.

2963

2964

<sect1 id="packages-arch-specific">When your package is not portable

2965

2966

Some packages still have issues with building and/or working on some

2967

of the architectures supported by Debian, and cannot be ported at all,

2968

or not within a reasonable amount of time. An example is a package that

2969

is SVGA-specific (only i386), or uses other hardware-specific features

2970

not supported on all architectures.

2971

2972

In order to prevent broken packages from being uploaded to the archive, and

2973

wasting buildd time, you need to do a few things:

2974

2975

<list>

2976

<item>

2977

2978

First, make sure your package does fail to build on

2979

architectures that it cannot support.

2980

There are a few ways to achieve this.

2981

The preferred way is to have a small testsuite during build time

2982

that will test the functionality, and fail if it doesn't work.

2983

This is a good idea anyway,

2984

as this will prevent (some) broken uploads on all architectures,

2985

and also will allow the package to build

2986

as soon as the required functionality is available.

2987

2988

Additionally, if you believe the list of supported architectures is

2989

pretty constant, you should change 'any' to a list of supported

2990

architectures in debian/control. This way, the build will fail also,

2991

and indicate this to a human reader without actually trying.

2992

<item>

2993

2994

In order to prevent autobuilders from needlessly trying to build your

2995

package, it must be included in <file>packages-arch-specific</file>, a

2996

list used by the <prgn>wanna-build</prgn> script.

2997

The current version is available as

2998

<url id="http://cvs.debian.org/srcdep/Packages-arch-specific?cvsroot=dak">;

2999

please see the top of the file for whom to contact for changes.

3000

</list>

3001

3002

Please note that it is insufficient to only add your package to

3003

Packages-arch-specific

3004

without making it fail to build on unsupported architectures:

3005

A porter or any other person trying to build your package might

3006

accidently upload it without noticing it doesn't work.

3007

If in the past some binary packages were uploaded on unsupported architectures,

3008

request their removal by filing a bug against

3009

<package>ftp.debian.org</package>

3010

3011

3012

<sect id="nmu">Non-Maintainer Uploads (NMUs)

3013

3014

Under certain circumstances it is necessary for someone other than the

3015

official package maintainer to make a release of a package. This is

3016

called a non-maintainer upload, or NMU.

3017

3018

This section handles only source NMUs, i.e. NMUs which upload a new

3019

version of the package. For binary-only NMUs by porters or QA members,

3020

please see <ref id="binary-only-nmu">.

3021

If a buildd builds and uploads a package,

3022

that too is strictly speaking a binary NMU.

3023

See <ref id="buildd"> for some more information.

3024

3025

The main reason why NMUs are done is when a

3026

developer needs to fix another developer's package in order to

3027

address serious problems or crippling bugs

3028

or when the package maintainer is unable to release a fix

3029

in a timely fashion.

3030

3031

First and foremost, it is critical that NMU patches to source should

3032

be as non-disruptive as possible. Do not do housekeeping tasks, do

3033

not change the name of modules or files, do not move directories; in

3034

general, do not fix things which are not broken. Keep the patch as

3035

small as possible. If things bother you aesthetically, talk to the

3036

Debian maintainer, talk to the upstream maintainer, or submit a bug.

3037

However, aesthetic changes must not be made in a non-maintainer

3038

upload.

3039

3040

And please remember the Hippocratic Oath: "Above all, do no harm." It

3041

is better to leave a package with an open grave bug than applying a

3042

non-functional patch, or one that hides the bug instead of resolving

3043

it.

3044

3045

3046

<sect1 id="nmu-guidelines">How to do a NMU

3047

3048

NMUs which fix important, serious or higher severity bugs are encouraged

3049

and accepted.

3050

You should endeavor to reach the current maintainer of the package; they

3051

might be just about to upload a fix for the problem, or have a better

3052

solution.

3053

3054

NMUs should be made to assist a package's maintainer in resolving bugs.

3055

Maintainers should be thankful for that help, and NMUers should respect

3056

the decisions of maintainers, and try to personally help the maintainer by

3057

their work.

3058

3059

A NMU should follow all conventions, written down in this section.

3060

For an upload to testing or unstable, this order of steps is recommended:

3061

3062

<list>

3063

<item>

3064

Make sure that the package's bugs that the NMU is meant to address are all

3065

filed in the Debian Bug Tracking System (BTS).

3066

If they are not, submit them immediately.

3067

<item>

3068

Wait a few days for the response from the maintainer. If you don't get

3069

any response, you may want to help them by sending the patch that fixes

3070

the bug. Don't forget to tag the bug with the "patch" keyword.

3071

<item>

3072

Wait a few more days. If you still haven't got an answer from the

3073

maintainer, send them a mail announcing your intent to NMU the package.

3074

Prepare an NMU as described in this section, and test it

3075

carefully on your machine (cf. <ref id="sanitycheck">).

3076

Double check that your patch doesn't have any unexpected side effects.

3077

Make sure your patch is as small and as non-disruptive as it can be.

3078

<item>

3079

Upload your package to incoming in <file>DELAYED/7-day</file> (cf.

3080

<ref id="delayed-incoming">), send the final patch to the maintainer via

3081

the BTS, and explain to them that they have 7 days to react if they want

3082

to cancel the NMU.

3083

<item>

3084

Follow what happens, you're responsible for any bug that you introduced

3085

with your NMU. You should probably use <ref id="pkg-tracking-system"> (PTS)

3086

to stay informed of the state of the package after your NMU.

3087

</list>

3088

3089

At times, the release manager or an organized group of developers can

3090

announce a certain period of time in which the NMU rules are relaxed.

3091

This usually involves shortening the period during which one is to wait

3092

before uploading the fixes, and shortening the DELAYED period. It is

3093

important to notice that even in these so-called "bug squashing party"

3094

times, the NMU'er has to file bugs and contact the developer first,

3095

and act later.

3096

Please see <ref id="qa-bsp"> for details.

3097

3098

For the testing distribution, the rules may be changed by the release

3099

managers. Please take additional care, and acknowledge that the usual way

3100

for a package to enter testing is through unstable.

3101

3102

For the stable distribution, please take extra care. Of course, the release

3103

managers may also change the rules here. Please verify before you upload that

3104

all your changes are OK for inclusion into the next stable release by the

3105

release manager.

3106

3107

When a security bug is detected, the security team may do an NMU, using

3108

their own rules. Please refer to <ref id="bug-security"> for more

3109

information.

3110

3111

For the differences for Porters NMUs, please see

3112

<ref id="source-nmu-when-porter">.

3113

3114

Of course, it is always possible to agree on special rules with a maintainer

3115

(like the maintainer asking "please upload this fix directly for me, and no

3116

diff required").

3117

3118

3119

<sect1 id="nmu-version">NMU version numbering

3120

3121

Whenever you have made a change to a package, no matter how trivial,

3122

the version number needs to change. This enables our packing system

3123

to function.

3124

3125

If you are doing a non-maintainer upload (NMU), you should add a new

3126

minor version number to the <var>debian-revision</var> part of the

3127

version number (the portion after the last hyphen). This extra minor

3128

number will start at `1'. For example, consider the package `foo',

3129

which is at version 1.1-3. In the archive, the source package control

3130

file would be <file>foo_1.1-3.dsc</file>. The upstream version is

3131

`1.1' and the Debian revision is `3'. The next NMU would add a new

3132

minor number `.1' to the Debian revision; the new source control file

3133

would be <file>foo_1.1-3.1.dsc</file>.

3134

3135

The Debian revision minor number is needed to avoid stealing one of

3136

the package maintainer's version numbers, which might disrupt their

3137

work. It also has the benefit of making it visually clear that a

3138

package in the archive was not made by the official maintainer.

3139

3140

If there is no <var>debian-revision</var> component in the version

3141

number then one should be created, starting at `0.1'. If it is

3142

absolutely necessary for someone other than the usual maintainer to

3143

make a release based on a new upstream version then the person making

3144

the release should start with the <var>debian-revision</var> value

3145

`0.1'. The usual maintainer of a package should start their

3146

<var>debian-revision</var> numbering at `1'.

3147

3148

If you upload a package to testing or stable, sometimes, you need to

3149

"fork" the version number tree. For this, version numbers like

3150

1.1-3sarge0.1 could be used.

3151

3152

3153

3154

<heading>Source NMUs must have a new changelog entry</heading>

3155

3156

Anyone who is doing a source NMU must create a changelog entry,

3157

describing which bugs are fixed by the NMU, and generally why the NMU

3158

was required and what it fixed. The changelog entry will have the

3159

email address of the person who uploaded it in the log entry

3160

and the NMU version number in it.

3161

3162

By convention, source NMU changelog entries start with the line

3163

3164

* Non-maintainer upload

3165

</example>

3166

3167

3168

<sect1 id="nmu-patch">Source NMUs and the Bug Tracking System

3169

3170

Maintainers other than the official package maintainer should make as

3171

few changes to the package as possible, and they should always send a

3172

patch as a unified context diff (<tt>diff -u</tt>) detailing their

3173

changes to the Bug Tracking System.

3174

3175

What if you are simply recompiling the package? If you just need to

3176

recompile it for a single architecture, then you may do a binary-only

3177

NMU as described in <ref id="binary-only-nmu"> which doesn't require any

3178

patch to be sent. If you want the package to be recompiled for all

3179

architectures, then you do a source NMU as usual and you will have to

3180

send a patch.

3181

3182

If the source NMU (non-maintainer upload) fixes some existing bugs,

3183

these bugs should be tagged fixed in the Bug Tracking

3184

System rather than closed. By convention, only the official package

3185

maintainer or the original bug submitter close bugs.

3186

Fortunately, Debian's archive system recognizes NMUs and thus marks

3187

the bugs fixed in the NMU appropriately if the person doing the NMU

3188

has listed all bugs in the changelog with the <tt>Closes:

3189

bug#<var>nnnnn</var></tt> syntax (see <ref id="upload-bugfix"> for

3190

more information describing how to close bugs via the changelog).

3191

Tagging the bugs fixed ensures that everyone knows that the

3192

bug was fixed in an NMU; however the bug is left open until the

3193

changes in the NMU are incorporated officially into the package by

3194

the official package maintainer.

3195

3196

Also, after doing an NMU, you have to send

3197

the information to the existing bugs that are fixed by your NMU,

3198

including the unified diff.

3199

Historically, it was custom to open a new bug and include a

3200

patch showing all the changes you have made.

3201

The normal maintainer will either apply the patch or employ an alternate

3202

method of fixing the problem. Sometimes bugs are fixed independently

3203

upstream, which is another good reason to back out an NMU's patch.

3204

If the maintainer decides not to apply the NMU's patch but to release a

3205

new version, the maintainer needs to ensure that the new upstream version

3206

really fixes each problem that was fixed in the non-maintainer release.

3207

3208

In addition, the normal maintainer should always retain the

3209

entry in the changelog file documenting the non-maintainer upload --

3210

and of course, also keep the changes.

3211

If you revert some of the changes,

3212

please reopen the relevant bug reports.

3213

3214

3215

<sect1 id="nmu-build">Building source NMUs

3216

3217

Source NMU packages are built normally. Pick a distribution using the

3218

same rules as found in <ref id="distribution">, follow the other

3219

instructions in <ref id="upload">.

3220

3221

Make sure you do not change the value of the maintainer in

3222

the <file>debian/control</file> file. Your name as given in the NMU entry of

3223

the <file>debian/changelog</file> file will be used for signing the

3224

changes file.

3225

3226

<sect1 id="ack-nmu">Acknowledging an NMU

3227

3228

If one of your packages has been NMU'ed, you have to incorporate the

3229

changes in your copy of the sources. This is easy, you just have

3230

to apply the patch that has been sent to you. Once this is done, you

3231

have to close the bugs that have been tagged fixed by the NMU. The easiest

3232

way is to use the <tt>-v</tt> option of <prgn>dpkg-buildpackage</prgn>,

3233

as this allows you to include just all changes since your last maintainer

3234

upload. Alternatively, you

3235

can close them manually by sending the required mails to the

3236

BTS or by adding the required <tt>closes: #nnnn</tt> in the changelog

3237

entry of your next upload.

3238

3239

In any case, you should not be upset by the NMU. An NMU is not a

3240

personal attack against the maintainer. It is a proof that

3241

someone cares enough about the package that they were willing to help

3242

you in your work, so you should be thankful. You may also want to

3243

ask them if they would be interested in helping you on a more frequent

3244

basis as co-maintainer or backup maintainer

3245

(see <ref id="collaborative-maint">).

3246

3247

<sect1 id="nmu-vs-qa">NMU vs QA uploads

3248

3249

Unless you know the maintainer is still active, it is wise to check the

3250

package to see if it has been orphaned. The current list of orphaned

3251

packages which haven't had their maintainer set correctly is available at

3252

<url id="&url-debian-qa-orphaned;">. If you perform an NMU on an

3253

improperly orphaned package, please set the maintainer to ``Debian QA Group

3254

<packages@qa.debian.org>''.

3255

3256

<sect1 id="nmu-who">Who can do an NMU

3257

3258

Only official, registered Debian Developers can do binary or source

3259

NMUs. A Debian Developer is someone who has their key in the

3260

Debian key ring. Non-developers, however, are encouraged to download

3261

the source package and start hacking on it to fix problems; however,

3262

rather than doing an NMU, they should just submit worthwhile patches

3263

to the Bug Tracking System. Maintainers almost always appreciate

3264

quality patches and bug reports.

3265

3266

<sect1 id="nmu-terms">Terminology

3267

3268

There are two new terms used throughout this section: ``binary-only NMU''

3269

and ``source NMU''. These terms are used with specific technical

3270

meaning throughout this document. Both binary-only and source NMUs are

3271

similar, since they involve an upload of a package by a developer who

3272

is not the official maintainer of that package. That is why it's a

3273

non-maintainer upload.

3274

3275

A source NMU is an upload of a package by a developer who is not the

3276

official maintainer, for the purposes of fixing a bug in the package.

3277

Source NMUs always involves changes to the source (even if it is just

3278

a change to <file>debian/changelog</file>). This can be either a

3279

change to the upstream source, or a change to the Debian bits of the

3280

source. Note, however, that source NMUs may also include

3281

architecture-dependent packages, as well as an updated Debian diff.

3282

3283

A binary-only NMU is a recompilation and upload of a binary package

3284

for a given architecture. As such, it is usually part of a porting

3285

effort. A binary-only NMU is a non-maintainer uploaded binary version

3286

of a package, with no source changes required. There are many cases

3287

where porters must fix problems in the source in order to get them to

3288

compile for their target architecture; that would be considered a

3289

source NMU rather than a binary-only NMU. As you can see, we don't

3290

distinguish in terminology between porter NMUs and non-porter NMUs.

3291

3292

Both classes of NMUs, source and binary-only, can be lumped under the

3293

term ``NMU''. However, this often leads to confusion, since most

3294

people think ``source NMU'' when they think ``NMU''. So it's best to

3295

be careful: always use ``binary NMU'' or ``binNMU'' for binary-only

3296

NMUs.

3297

3298

3299

3300

<heading>Collaborative maintenance</heading>

3301

3302

"Collaborative maintenance" is a term describing the sharing of Debian

3303

package maintenance duties by several people. This collaboration is

3304

almost always a good idea, since it generally results in higher quality and

3305

faster bug fix turnaround times. It is strongly recommended that

3306

packages with a priority of <tt>Standard</tt> or which are part of

3307

the base set have co-maintainers.

3308

3309

Generally there is a primary maintainer and one or more

3310

co-maintainers. The primary maintainer is the person whose name is listed in

3311

the <tt>Maintainer</tt> field of the <file>debian/control</file> file.

3312

Co-maintainers are all the other maintainers.

3313

3314

In its most basic form, the process of adding a new co-maintainer is

3315

quite easy:

3316

<list>

3317

<item>

3318

3319

Setup the co-maintainer with access to the sources you build the

3320

package from. Generally this implies you are using a network-capable

3321

version control system, such as <prgn>CVS</prgn> or

3322

<prgn>Subversion</prgn>.

3323

</item>

3324

<item>

3325

3326

Add the co-maintainer's correct maintainer name and address to the

3327

<tt>Uploaders</tt> field in the global part of the

3328

<file>debian/control</file> file.

3329

3330

Uploaders: John Buzz <jbuzz@debian.org>, Adam Rex <arex@debian.org>

3331

</example>

3332

3333

</item>

3334

<item>

3335

3336

Using the PTS (<ref id="pkg-tracking-system">), the co-maintainers

3337

should subscribe themselves to the appropriate source package.

3338

</item>

3339

</list>

3340

3341

Collaborative maintenance can often be further eased by the use of

3342

tools on Alioth (see <ref id="alioth">).

3343

</sect>

3344

3345

3346

<heading>The testing distribution</heading>

3347

3348

3349

<heading>Basics</heading>

3350

3351

Packages are usually installed into the `testing' distribution after they

3352

have undergone some degree of testing in unstable.

3353

3354

They must be in sync on all architectures and

3355

mustn't have dependencies that make them uninstallable; they also have to

3356

have generally no known release-critical bugs at the time they're

3357

installed into testing.

3358

This way, `testing' should always be close to being a release candidate.

3359

Please see below for details.

3360

3361

<heading>Updates from unstable</heading>

3362

3363

The scripts that update the testing distribution are run each

3364

day after the installation of the updated packages;

3365

these scripts are called britney.

3366

They generate the

3367

<file>Packages</file> files for the testing distribution, but

3368

they do so in an intelligent manner; they try to avoid any inconsistency

3369

and to use only non-buggy packages.

3370

3371

The inclusion of a package from unstable is conditional on

3372

the following:

3373

<list>

3374

<item>

3375

The package must have been available in unstable for 2, 5 or 10

3376

days, depending on the urgency (high, medium or low).

3377

Please note that the urgency is sticky, meaning that the highest

3378

urgency uploaded since the previous testing transition is taken into account.

3379

Those delays may be doubled during a freeze, or testing transitions may be

3380

switched off altogether;

3381

<item>

3382

It must have the same number or fewer release-critical bugs than the version currently available

3383

in testing;

3384

<item>

3385

It must be available on all architectures on which it has previously

3386

been built in unstable. <ref id="madison"> may be of interest to

3387

check that information;

3388

<item>

3389

It must not break any dependency of a package which is already available

3390

in testing;

3391

<item>

3392

The packages on which it depends must either be available in testing

3393

or they must be accepted into testing at the same time (and they will

3394

be if they fulfill all the necessary criteria);

3395

</list>

3396

3397

To find out whether a package is progressing into testing or not, see the

3398

testing script output on the <url name="web page of the testing distribution"

3399

id="&url-testing-maint;">, or use the program <prgn>grep-excuses</prgn>

3400

which is in the <package>devscripts</package> package. This utility can

3401

easily be used in a <manref name="crontab" section="5"> to keep yourself

3402

informed of the progression of your packages into testing.

3403

3404

The <file>update_excuses</file> file does not always give the precise reason

3405

why the package is refused; you may have to find it on your own by looking

3406

for what would break with the inclusion of the package. The

3407

<url id="&url-testing-maint;" name="testing web page"> gives some more

3408

information about the usual problems which may be causing such troubles.

3409

3410

Sometimes, some packages never enter testing because the set of

3411

inter-relationship is too complicated and cannot be sorted out

3412

by the scripts. See below for details.

3413

3414

Some further dependency analysis is shown on

3415

<url id="http://bjorn.haxx.se/debian/"> — but be warned,

3416

this page also shows build dependencies which

3417

are not considered by britney.

3418

3419

3420

3421

3422

3423

For the testing migration script, "outdated" means: There are different

3424

versions in unstable for the release architectures (except for the

3425

architectures in fuckedarches; fuckedarches is a list of architectures

3426

that don't keep up (in update_out.py), but currently, it's empty).

3427

"outdated" has nothing whatsoever to do with the architectures this package

3428

has in testing.

3429

3430

Consider this example:

3431

3432

3433

foo | alpha | arm

3434

---------+-------+----

3435

testing | 1 | -

3436

unstable | 1 | 2

3437

</example>

3438

3439

The package is out of date on alpha in unstable, and will not go to

3440

testing. And removing foo from testing would not help at all, the package

3441

is still out of date on alpha, and will not propagate to testing.

3442

3443

However, if ftp-master removes a package in unstable (here on arm):

3444

3445

3446

foo | alpha | arm | hurd-i386

3447

---------+-------+-----+----------

3448

testing | 1 | 1 | -

3449

unstable | 2 | - | 1

3450

</example>

3451

3452

In this case, the package is up to date on all release architectures in

3453

unstable (and the extra hurd-i386 doesn't matter, as it's not a release

3454

architecture).

3455

3456

Sometimes, the question is raised if it is possible to allow packages in

3457

that are not yet built on all architectures: No. Just plainly no. (Except

3458

if you maintain glibc or so.)

3459

3460

3461

<heading>Removals from testing</heading>

3462

3463

Sometimes, a package is removed to allow another package in: This happens

3464

only to allow another package to go in if it's ready in every other

3465

sense. Suppose e.g. that a cannot be installed with the new version of

3466

b; then a may be removed to allow b in.

3467

3468

Of course, there is another reason to remove a package from testing: It's

3469

just too buggy (and having a single RC-bug is enough to be in this state).

3470

3471

Furthermore, if a package has been removed from unstable,

3472

and no package in testing depends on it any more,

3473

then it will automatically be removed.

3474

3475

3476

3477

<heading>circular dependencies</heading>

3478

3479

A situation which is not handled very well by britney is if package a

3480

depends on the new version of package b, and vice versa.

3481

3482

An example of this is:

3483

3484

3485

| testing | unstable

3486

--+-----------------+------------

3487

a | 1; depends: b=1 | 2; depends: b=2

3488

b | 1; depends: a=1 | 2; depends: a=2

3489

</example>

3490

3491

Neither package a nor package b is considered for update.

3492

3493

Currently, this requires some manual hinting from the release team.

3494

Please contact them by sending mail to &email-debian-release; if this

3495

happens to one of your packages.

3496

3497

3498

<sect2>

3499

<heading>influence of package in testing</heading>

3500

3501

Generally, there is nothing that the status of a package in testing means

3502

for transition of the next version from unstable to testing, with two

3503

exceptions: If the RC-bugginess of the package goes down, it may go in

3504

even if it is still RC-buggy. The second exception is if the version

3505

of the package in testing is out of sync on the different arches: Then

3506

any arch might just upgrade to the version of the source package;

3507

however, this can happen only if the package was previously forced

3508

through, the arch is in fuckedarches, or there was no binary package of that

3509

arch present in unstable at all during the testing migration.

3510

3511

In summary this means: The only influence that a package being in testing

3512

has on a new version of the same package is that the new version might

3513

go in easier.

3514

3515

3516

<heading>details</heading>

3517

3518

If you are interested in details, this is how britney works:

3519

3520

The packages are looked at to determine whether they are valid

3521

candidates. This gives the "update excuses". The most common reasons

3522

why a package is not considered are too young, RC-bugginess, and out of

3523

date on some arches. For this part of britney,

3524

the release managers have hammers

3525

of various sizes to force britney to consider a package. (Also, the base

3526

freeze is coded in that part of britney.) (There is a similar thing

3527

for binary-only updates, but this is not described here. If you're

3528

interested in that, please peruse the code.)

3529

3530

Now, the more complex part happens: Britney tries to update testing with

3531

the valid candidates; first, each package alone, and then larger and even

3532

larger sets of packages together. Each try is accepted if testing is not

3533

more uninstallable after the update than before. (Before and after this part,

3534

some hints are processed; but as only release masters can hint, this is

3535

probably not so important for you.)

3536

3537

If you want to see more details, you can look it up on

3538

merkel:/org/ftp.debian.org/testing/update_out/ (or there in

3539

~aba/testing/update_out to see a setup with a smaller packages file). Via

3540

web, it's at <url

3541

id="http://ftp-master.debian.org/testing/update_out_code/">

3542

3543

The hints are available via <url

3544

id="http://ftp-master.debian.org/testing/hints/">.

3545

3546

3547

3548

<heading>Direct updates to testing</heading>

3549

3550

The testing distribution is fed with packages from unstable according to the rules

3551

explained above. However, in some cases, it is necessary to upload

3552

packages built only for testing. For that, you may want to

3553

upload to testing-proposed-updates.

3554

3555

Keep in mind that packages uploaded there are not automatically processed, they

3556

have to go through the hands of the release manager. So you'd better have a good

3557

reason to upload there. In order to know what a good reason is in the

3558

release managers' eyes, you should read the instructions that they regularly

3559

give on &email-debian-devel-announce;.

3560

3561

You should not upload to testing-proposed-updates when you can update your

3562

packages through unstable. If you can't (for example because you have a

3563

newer development version in unstable), you may use this facility,

3564

but it is recommended that you ask for authorization from

3565

the release manager first.

3566

Even if a package is

3567

frozen, updates through unstable are possible, if the upload via unstable

3568

does not pull in any new dependencies.

3569

3570

Version numbers are usually selected by adding the codename of the testing

3571

distribution and a running number, like 1.2sarge1 for the first upload

3572

through testing-proposed-updates of package version 1.2.

3573

3574

Please make sure you didn't miss any of these items in your upload:

3575

<list>

3576

<item> Make sure that your package really needs to go through

3577

testing-proposed-updates, and can't go through unstable;

3578

<item> Make sure that you included only the minimal amount of changes;

3579

<item> Make sure that you included an appropriate explanation in the

3580

changelog;

3581

<item> Make sure that you've written testing or

3582

testing-proposed-updates into your target distribution;

3583

<item> Make sure that you've built and tested your package in

3584

testing, not in unstable;

3585

<item> Make sure that your version number is higher than the version in

3586

testing and testing-proposed-updates, and lower than in

3587

unstable;

3588

<item> After uploading and successful build on all platforms, contact the

3589

release team at &email-debian-release; and ask them to approve your upload.

3590

</list>

3591

3592

3593

3594

<heading>Frequently asked questions</heading>

3595

3596

3597

3598

<heading>What are release-critical bugs, and how do they get counted?</heading>

3599

3600

All bugs of some higher severities are by default considered release-critical; currently, these are critical, grave, and serious bugs.

3601

3602

Such bugs are presumed to have an impact on the chances that the package will be released with the stable release of Debian: in general, if a package has open release-critical bugs filed on it, it won't get into "testing", and consequently won't be released in "stable".

3603

3604

The unstable bug count are all release-critical bugs

3605

without either any release-tag (such as potato, woody) or with release-tag sid;

3606

also, only if they are neither fixed nor set to sarge-ignore.

3607

The "testing" bug count for a package is considered to be roughly

3608

the bug count of unstable count at the last point

3609

when the "testing" version equalled the "unstable" version.

3610

3611

This will change post-sarge, as soon as we have versions in the bug tracking system.

3612

3613

3614

<sect2>

3615

<heading>How could installing a package into "testing" possibly break other packages?</heading>

3616

3617

The structure of the distribution archives is such that they can only contain one version of a package; a package is defined by its name. So when the source package acmefoo is installed into "testing", along with its binary packages acme-foo-bin, acme-bar-bin, libacme-foo1 and libacme-foo-dev, the old version is removed.

3618

3619

However, the old version may have provided a binary package with an old soname of a library, such as libacme-foo0. Removing the old acmefoo will remove libacme-foo0, which will break any packages which depend on it.

3620

3621

Evidently, this mainly affects packages which provide changing sets of binary packages in different versions (in turn, mainly libraries). However, it will also affect packages upon which versioned dependencies have been declared of the ==, <=, or << varieties.

3622

3623

When the set of binary packages provided by a source package change in this way, all the packages that depended on the old binaries will have to be updated to depend on the new binaries instead. Because installing such a source package into "testing" breaks all the packages that depended on it in "testing", some care has to be taken now: all the depending packages must be updated and ready to be installed themselves so that they won't be broken, and, once everything is ready, manual intervention by the release manager or an assistant is normally required.

3624

3625

If you are having problems with complicated groups of packages like this, contact debian-devel or debian-release for help.

3626

</sect>

3627

3628

3629

<heading>Best Packaging Practices</heading>

3630

3631

Debian's quality is largely due to the <url id="&url-debian-policy;"

3632

name="Debian Policy">, which defines explicit baseline requirements

3633

which all Debian packages must fulfill. Yet there is also a shared

3634

history of experience which goes beyond the Debian Policy, an

3635

accumulation of years of experience in packaging. Many very

3636

talented people have created great tools, tools which help you, the

3637

Debian maintainer, create and maintain excellent packages.

3638

3639

This chapter provides some best practices for Debian developers. All

3640

recommendations are merely that, and are not requirements or policy.

3641

These are just some subjective hints, advice and pointers collected

3642

from Debian developers. Feel free to pick and choose whatever works

3643

best for you.

3644

3645

3646

<heading>Best practices for <file>debian/rules</file></heading>

3647

3648

The following recommendations apply to the <file>debian/rules</file>

3649

file. Since <file>debian/rules</file> controls the build process and

3650

selects the files which go into the package (directly or indirectly),

3651

it's usually the file maintainers spend the most time on.

3652

3653

<sect1 id="helper-scripts">Helper scripts

3654

3655

The rationale for using helper scripts in <file>debian/rules</file> is

3656

that they let maintainers use and share common logic among many packages.

3657

Take for instance the question of installing menu entries: you need to

3658

put the file into <file>/usr/lib/menu</file> (or

3659

<file>/usr/lib/menu</file> for executable binary menufiles, if this is needed),

3660

and add commands to the

3661

maintainer scripts to register and unregister the menu entries. Since

3662

this is a very common thing for packages to do, why should each

3663

maintainer rewrite all this on their own, sometimes with bugs? Also,

3664

supposing the menu directory changed, every package would have to be

3665

changed.

3666

3667

Helper scripts take care of these issues. Assuming you comply with

3668

the conventions expected by the helper script, the helper takes care

3669

of all the details. Changes in policy can be made in the helper

3670

script; then packages just need to be rebuilt with the new version of

3671

the helper and no other changes.

3672

3673

<ref id="tools"> contains a couple of different helpers. The most

3674

common and best (in our opinion) helper system is

3675

<package>debhelper</package>. Previous helper systems, such as

3676

<package>debmake</package>, were "monolithic": you couldn't pick and

3677

choose which part of the helper you found useful, but had to use the

3678

helper to do everything. <package>debhelper</package>, however, is a

3679

number of separate little <prgn>dh_*</prgn> programs. For instance,

3680

<prgn>dh_installman</prgn> installs and compresses man pages,

3681

<prgn>dh_installmenu</prgn> installs menu files, and so on. Thus, it

3682

offers enough flexibility to be able to use the little helper scripts,

3683

where useful, in conjunction with hand-crafted commands in

3684

<file>debian/rules</file>.

3685

3686

You can get started with <package>debhelper</package> by reading

3687

<manref name="debhelper" section="1">, and looking at the examples

3688

that come with the package. <prgn>dh_make</prgn>, from the

3689

<package>dh-make</package> package (see <ref id="dh-make">), can be

3690

used to convert a "vanilla" source package to a

3691

<package>debhelper</package>ized package. This shortcut, though,

3692

should not convince you that you do not need to bother understanding

3693

the individual <prgn>dh_*</prgn> helpers. If you are going to use a

3694

helper, you do need to take the time to learn to use that helper, to

3695

learn its expectations and behavior.

3696

3697

Some people feel that vanilla <file>debian/rules</file> files are

3698

better, since you don't have to learn the intricacies of any helper

3699

system. This decision is completely up to you. Use what works for

3700

you. Many examples of vanilla <file>debian/rules</file> files are

3701

available at <url id="&url-rules-files;">.

3702

3703

3704

3705

<heading>Separating your patches into multiple files</heading>

3706

3707

Big, complex packages may have many bugs that you need to deal with.

3708

If you correct a number of bugs directly in the source, and you're not

3709

careful, it can get hard to differentiate the various patches that you

3710

applied. It can get quite messy when you have to update the package

3711

to a new upstream version which integrates some of the fixes (but not

3712

all). You can't take the total set of diffs (e.g., from

3713

<file>.diff.gz</file>) and work out which patch sets to back out as a

3714

unit as bugs are fixed upstream.

3715

3716

Unfortunately, the packaging system as such currently doesn't provide for

3717

separating the patches into several files. Nevertheless, there are ways to

3718

separate patches: the patch files are shipped within the Debian patch file

3719

(<file>.diff.gz</file>), usually within the <file>debian/</file> directory.

3720

The only difference is that they aren't applied immediately by dpkg-source,

3721

but by the <tt>build</tt> rule of <file>debian/rules</file>. Conversely,

3722

they are reverted in the <tt>clean</tt> rule.

3723

3724

<prgn>dbs</prgn> is one of the more popular approaches to this. It does all

3725

of the above, and provides a facility for creating new and updating old

3726

patches. See the package <package>dbs</package> for more information and

3727

<package>hello-dbs</package> for an example.

3728

3729

<prgn>dpatch</prgn> also provides these facilities, but it's intended to be

3730

even easier to use. See the package <package>dpatch</package> for

3731

documentation and examples (in <file>/usr/share/doc/dpatch</file>).

3732

3733

3734

<sect1 id="multiple-binary">Multiple binary packages

3735

3736

A single source package will often build several binary packages,

3737

either to provide several flavors of the same software (e.g.,

3738

the <package>vim</package> source package) or to make several small

3739

packages instead of a big one (e.g., so the user can install only the

3740

subset needed, and thus save some disk space).

3741

3742

The second case can be easily managed in <file>debian/rules</file>.

3743

You just need to move the appropriate files from the build directory

3744

into the package's temporary trees. You can do this using

3745

<prgn>install</prgn> or <prgn>dh_install</prgn>

3746

from <package>debhelper</package>. Be sure to check the different

3747

permutations of the various packages, ensuring that you have the

3748

inter-package dependencies set right in <file>debian/control</file>.

3749

3750

The first case is a bit more difficult since it involves multiple

3751

recompiles of the same software but with different configuration

3752

options. The <package>vim</package> source package is an example of how to manage

3753

this using an hand-crafted <file>debian/rules</file> file.

3754

3755

<!-- &FIXME; Find a good debhelper example with multiple configure/make

3756

cycles -->

3757

</sect1>

3758

</sect>

3759

3760

3761

3762

<heading>Best practices for <file>debian/control</file></heading>

3763

3764

The following practices are relevant to the

3765

<file>debian/control</file> file. They supplement the <url

3766

id="&url-debian-policy;ch-binary.html#s-descriptions"

3767

name="Policy on package descriptions">.

3768

3769

The description of the package, as defined by the corresponding field

3770

in the <file>control</file> file, contains both the package synopsis

3771

and the long description for the package. <ref id="bpp-desc-basics">

3772

describes common guidelines for both parts of the package description.

3773

Following that, <ref id="bpp-pkg-synopsis"> provides guidelines

3774

specific to the synopsis, and <ref id="bpp-pkg-desc"> contains

3775

guidelines specific to the description.

3776

3777

3778

<heading>General guidelines for package descriptions</heading>

3779

3780

The package description should be written for the average likely user,

3781

the average person who will use and benefit from the package. For

3782

instance, development packages are for developers, and can be

3783

technical in their language. More general-purpose applications, such

3784

as editors, should be written for a less technical user.

3785

3786

Our review of package descriptions lead us to conclude that most

3787

package descriptions are technical, that is, are not written to make

3788

sense for non-technical users. Unless your package really is only for

3789

technical users, this is a problem.

3790

3791

How do you write for non-technical users? Avoid jargon. Avoid

3792

referring to other applications or frameworks that the user might not

3793

be familiar with — "GNOME" or "KDE" is fine, since users are

3794

probably familiar with these terms, but "GTK+" is

3795

probably not. Try not to assume any knowledge at all. If you must

3796

use technical terms, introduce them.

3797

3798

Be objective. Package descriptions are not the place for advocating

3799

your package, no matter how much you love it. Remember that the

3800

reader may not care about the same things you care about.

3801

3802

References to the names of any other software packages, protocol names,

3803

standards, or specifications should use their canonical forms, if one

3804

exists. For example, use "X Window System", "X11", or "X"; not "X

3805

Windows", "X-Windows", or "X Window". Use "GTK+", not "GTK" or "gtk".

3806

Use "GNOME", not "Gnome". Use "PostScript", not "Postscript" or

3807

"postscript".

3808

3809

If you are having problems writing your description, you may wish to

3810

send it along to &email-debian-l10n-english; and request feedback.

3811

</sect1>

3812

3813

3814

3815

<heading>The package synopsis, or short description</heading>

3816

3817

The synopsis line (the short description) should be concise. It

3818

must not repeat the package's name (this is policy).

3819

3820

It's a good idea to think of the synopsis as an appositive clause, not

3821

a full sentence. An appositive clause is defined in WordNet as a

3822

grammatical relation between a word and a noun phrase that follows,

3823

e.g., "Rudolph the red-nosed reindeer". The appositive clause here is

3824

"red-nosed reindeer". Since the synopsis is a clause, rather than a

3825

full sentence, we recommend that it neither start with a capital nor

3826

end with a full stop (period). It should also not begin with an

3827

article, either definite ("the") or indefinite ("a" or "an").

3828

3829

It might help to imagine that the synopsis is combined with the

3830

package name in the following way:

3831

3832

<example><var>package-name</var> is a <var>synopsis</var>.</example>

3833

3834

Alternatively, it might make sense to think of it as

3835

3836

<example><var>package-name</var> is <var>synopsis</var>.</example>

3837

3838

or, if the package name itself is a plural (such as

3839

"developers-tools")

3840

3841

<example><var>package-name</var> are <var>synopsis</var>.</example>

3842

3843

This way of forming a sentence from the package name and synopsis

3844

should be considered as a heuristic and not a strict rule. There are

3845

some cases where it doesn't make sense to try to form a sentence.

3846

</sect1>

3847

3848

3849

<heading>The long description</heading>

3850

3851

The long description is the primary information available to the user

3852

about a package before they install it. It should provide all the

3853

information needed to let the user decide whether to install the

3854

package. Assume that the user has already read the package synopsis.

3855

3856

The long description should consist of full and complete sentences.

3857

3858

The first paragraph of the long description should answer the

3859

following questions: what does the package do? what task does it help

3860

the user accomplish? It is important to describe this in a

3861

non-technical way, unless of course the audience for the package is

3862

necessarily technical.

3863

3864

The following paragraphs should answer the following questions: Why do

3865

I as a user need this package? What other features does the package

3866

have? What outstanding features and deficiencies are there compared

3867

to other packages (e.g., "if you need X, use Y instead")? Is this

3868

package related to other packages in some way that is not handled by

3869

the package manager (e.g., "this is the client for the foo server")?

3870

3871

Be careful to avoid spelling and grammar mistakes. Ensure that you

3872

spell-check it. Both <prgn>ispell</prgn> and <prgn>aspell</prgn>

3873

have special modes for checking <file>debian/control</file> files:

3874

3875

<example>ispell -d american -g debian/control</example>

3876

<example>aspell -d en -D -c debian/control</example>

3877

3878

Users usually expect these questions to be answered in the package

3879

description:

3880

<list>

3881

<item>

3882

What does the package do? If it is an add-on to another package,

3883

then the short description of the package we are an add-on to

3884

should be put in here.

3885

<item>

3886

Why should I want this package? This is related to the above,

3887

but not the same (this is a mail user agent; this is cool, fast,

3888

interfaces with PGP and LDAP and IMAP, has features X, Y, and Z).

3889

<item>

3890

If this package should not be installed directly, but is pulled in

3891

by another package, this should be mentioned.

3892

<item>

3893

If the package is experimental, or there are other reasons it

3894

should not be used, if there are other packages that should be

3895

used instead, it should be here as well.

3896

<item>

3897

How is this package different from the competition? Is it a better

3898

implementation? more features? different features? Why should I

3899

choose this package.

3900

<!-- FIXME: what's this?

3901

(the second questions is about the class of packages, and

3902

this about this particular package, if you have information related to both).

3903

-->

3904

</list>

3905

3906

</sect1>

3907

3908

3909

3910

<heading>Upstream home page</heading>

3911

3912

We recommend that you add the URL for the package's home page to the

3913

package description in <file>debian/control</file>. This information

3914

should be added at the

3915

end of description, using the following format:

3916

3917

<example> .

3918

Homepage: http://some-project.some-place.org/</example>

3919

3920

Note the spaces prepending the line, which serves to break the lines

3921

correctly. To see an example of how this displays, see <url

3922

id="&url-eg-desc-upstream-info;">.

3923

3924

If there is no home page for the software, this should naturally be

3925

left out.

3926

3927

Note that we expect this field will eventually be replaced by a proper

3928

<file>debian/control</file> field understood by <prgn>dpkg</prgn> and

3929

<tt>&packages-host;</tt>. If you don't want to bother migrating the

3930

home page from the description to this field, you should probably wait

3931

until that is available.

3932

Please make sure that this line matches the regular expression

3933

<tt>/^ Homepage: [^ ]*$/</tt>,

3934

as this allows <file>packages.debian.org</file> to parse it correctly.

3935

</sect1>

3936

</sect>

3937

3938

3939

3940

<heading>Best practices for <file>debian/changelog</file></heading>

3941

3942

The following practices supplement the <url name="Policy on changelog

3943

files" id="&url-debian-policy;ch-docs.html#s-changelogs">.

3944

3945

3946

<heading>Writing useful changelog entries</heading>

3947

3948

The changelog entry for a package revision documents changes in that

3949

revision, and only them. Concentrate on describing significant and

3950

user-visible changes that were made since the last version.

3951

3952

Focus on what was changed — who, how and when are

3953

usually less important. Having said that, remember to politely

3954

attribute people who have provided notable help in making the package

3955

(e.g., those who have sent in patches).

3956

3957

There's no need to elaborate the trivial and obvious changes. You can

3958

also aggregate several changes in one entry. On the other hand, don't

3959

be overly terse if you have undertaken a major change. Be especially

3960

clear if there are changes that affect the behaviour of the program.

3961

For further explanations, use the <file>README.Debian</file> file.

3962

3963

Use common English so that the majority of readers can comprehend it.

3964

Avoid abbreviations, "tech-speak" and jargon when explaining changes

3965

that close bugs, especially for bugs filed by users that did not

3966

strike you as particularly technically savvy. Be polite, don't swear.

3967

3968

It is sometimes desirable to prefix changelog entries with the names

3969

of the files that were changed. However, there's no need to

3970

explicitly list each and every last one of the changed files,

3971

especially if the change was small or repetitive. You may use

3972

wildcards.

3973

3974

When referring to bugs, don't assume anything. Say what the problem

3975

was, how it was fixed, and append the "closes: #nnnnn" string. See

3976

<ref id="upload-bugfix"> for more information.

3977

3978

3979

3980

<heading>Common misconceptions about changelog entries</heading>

3981

3982

The changelog entries should not document generic

3983

packaging issues ("Hey, if you're looking for foo.conf, it's in

3984

/etc/blah/."), since administrators and users are supposed to be at

3985

least remotely acquainted with how such things are generally arranged

3986

on Debian systems. Do, however, mention if you change the location of

3987

a configuration file.

3988

3989

The only bugs closed with a changelog entry should be those that are

3990

actually fixed in the same package revision. Closing unrelated bugs

3991

in the changelog is bad practice. See <ref id="upload-bugfix">.

3992

3993

The changelog entries should not be used for random

3994

discussion with bug reporters ("I don't see segfaults when starting

3995

foo with option bar; send in more info"), general statements on life,

3996

the universe and everything ("sorry this upload took me so long, but I

3997

caught the flu"), or pleas for help ("the bug list on this package is

3998

huge, please lend me a hand"). Such things usually won't be noticed

3999

by their target audience, but may annoy people who wish to read

4000

information about actual changes in the package. See <ref

4001

id="bug-answering"> for more information on how to use the bug

4002

tracking system.

4003

4004

It is an old tradition to acknowledge bugs fixed in non-maintainer

4005

uploads in the first changelog entry of the proper maintainer upload.

4006

As we have version tracking now,

4007

it is enough to keep the NMUed changelog entries and

4008

just mention this fact in your own changelog entry.

4009

</sect1>

4010

4011

4012

<heading>Common errors in changelog entries</heading>

4013

4014

The following examples demonstrate some common errors or examples of

4015

bad style in changelog entries.

4016

4017

4018

4019

* Fixed all outstanding bugs.

4020

</example>

4021

This doesn't tell readers anything too useful, obviously.

4022

4023

4024

4025

* Applied patch from Jane Random.

4026

</example>

4027

What was the patch about?

4028

4029

4030

4031

* Late night install target overhaul.

4032

</example>

4033

Overhaul which accomplished what? Is the mention of late night

4034

supposed to remind us that we shouldn't trust that code?

4035

4036

4037

4038

* Fix vsync FU w/ ancient CRTs.

4039

</example>

4040

Too many acronyms, and it's not overly clear what the, uh, fsckup (oops,

4041

a curse word!) was actually about, or how it was fixed.

4042

4043

4044

4045

* This is not a bug, closes: #nnnnnn.

4046

</example>

4047

First of all, there's absolutely no need to upload the package to

4048

convey this information; instead, use the bug tracking system.

4049

Secondly, there's no explanation as to why the report is not a bug.

4050

4051

4052

4053

* Has been fixed for ages, but I forgot to close; closes: #54321.

4054

</example>

4055

If for some reason you didn't mention the bug number in a previous changelog

4056

entry, there's no problem, just close the bug normally in the BTS. There's

4057

no need to touch the changelog file, presuming the description of the fix is

4058

already in (this applies to the fixes by the upstream authors/maintainers as

4059

well, you don't have to track bugs that they fixed ages ago in your

4060

changelog).

4061

4062

4063

4064

* Closes: #12345, #12346, #15432

4065

</example>

4066

Where's the description? If you can't think of a descriptive message,

4067

start by inserting the title of each different bug.

4068

</sect1>

4069

4070

4071

<heading>Supplementing changelogs with NEWS.Debian files</heading>

4072

4073

Important news about changes in a package can also be put in NEWS.Debian

4074

files. The news will be displayed by tools like apt-listchanges, before

4075

all the rest of the changelogs. This is the preferred means to let the user

4076

know about significant changes in a package. It is better than using

4077

debconf notes since it is less annoying and the user can go back and refer

4078

to the NEWS.Debian file after the install. And it's better than listing

4079

major changes in README.Debian, since the user can easily miss such notes.

4080

4081

The file format is the same as a debian changelog file, but leave off

4082

the asterisks and describe each news item with a full paragraph when

4083

necessary rather than the more concise summaries that would go in a

4084

changelog. It's a good idea to run your file through dpkg-parsechangelog to

4085

check its formatting as it will not be automatically checked during build

4086

as the changelog is. Here is an example of a real NEWS.Debian file:

4087

4088

cron (3.0pl1-74) unstable; urgency=low

4089

4090

The checksecurity script is no longer included with the cron package:

4091

it now has its own package, "checksecurity". If you liked the

4092

functionality provided with that script, please install the new

4093

package.

4094

4095

-- Steve Greenland <stevegr@debian.org> Sat, 6 Sep 2003 17:15:03 -0500

4096

</example>

4097

4098

The NEWS.Debian file is installed as

4099

/usr/share/doc/<package>/NEWS.Debian.gz. It is compressed, and

4100

always has that name even in Debian native packages. If you use debhelper,

4101

dh_installchangelogs will install debian/NEWS files for you.

4102

4103

Unlike changelog files, you need not update NEWS.Debian files with every

4104

release. Only update them if you have something particularly newsworthy

4105

that user should know about. If you have no news at all, there's no need

4106

to ship a NEWS.Debian file in your package. No news is good news!

4107

</sect>

4108

4109

<!--

4110

<sect1 id="pkg-mgmt-cvs">Managing a package with CVS

4111

4112

&FIXME; presentation of cvs-buildpackage, updating sources

4113

via CVS (debian/rules refresh).

4114

4115

-->

4116

4117

4118

4119

<heading>Best practices for maintainer scripts</heading>

4120

4121

Maintainer scripts include the files <file>debian/postinst</file>,

4122

<file>debian/preinst</file>, <file>debian/prerm</file> and

4123

<file>debian/postrm</file>. These scripts take care of any package

4124

installation or deinstallation setup which isn't handled merely by the

4125

creation or removal of files and directories. The following

4126

instructions supplement the <url id="&url-debian-policy;" name="Debian

4127

Policy">.

4128

4129

Maintainer scripts must be idempotent. That means that you need to

4130

make sure nothing bad will happen if the script is called twice where

4131

it would usually be called once.

4132

4133

Standard input and output may be redirected (e.g. into pipes) for

4134

logging purposes, so don't rely on them being a tty.

4135

4136

All prompting or interactive configuration should be kept to a

4137

minimum. When it is necessary, you should use the

4138

<package>debconf</package> package for the interface. Remember that

4139

prompting in any case can only be in the <tt>configure</tt> stage of

4140

the <file>postinst</file> script.

4141

4142

Keep the maintainer scripts as simple as possible. We suggest you use

4143

pure POSIX shell scripts. Remember, if you do need any bash features,

4144

the maintainer script must have a bash shebang line. POSIX shell or

4145

Bash are preferred to Perl, since they enable

4146

<package>debhelper</package> to easily add bits to the scripts.

4147

4148

If you change your maintainer scripts, be sure to test package

4149

removal, double installation, and purging. Be sure that a purged

4150

package is completely gone, that is, it must remove any files created,

4151

directly or indirectly, in any maintainer script.

4152

4153

If you need to check for the existence of a command, you should use

4154

something like

4155

<example>if [ -x /usr/sbin/install-docs ]; then ...</example>

4156

4157

If you don't wish to hard-code the path of a command in your

4158

maintainer script, the following POSIX-compliant shell function may

4159

help:

4160

4161

&example-pathfind;

4162

4163

You can use this function to search <tt>$PATH</tt> for a command name,

4164

passed as an argument. It returns true (zero) if the command was

4165

found, and false if not. This is really the most portable way, since

4166

<tt>command -v</tt>, <prgn>type</prgn>, and <prgn>which</prgn> are not

4167

POSIX.

4168

4169

While <prgn>which</prgn> is an acceptable alternative, since

4170

it is from the required <package>debianutils</package> package, it's

4171

not on the root partition. That is, it's in <file>/usr/bin</file> rather

4172

than <file>/bin</file>, so one can't use it in scripts which are run

4173

before the <file>/usr</file> partition is mounted. Most scripts won't have

4174

this problem, though.

4175

</sect>

4176

4177

4178

4179

<heading>Configuration management with <package>debconf</package></heading>

4180

4181

<package>Debconf</package> is a configuration management system which

4182

can be used by all the various packaging scripts

4183

(<file>postinst</file> mainly) to request feedback from the user

4184

concerning how to configure the package. Direct user interactions must

4185

now be avoided in favor of <package>debconf</package>

4186

interaction. This will enable non-interactive installations in the

4187

future.

4188

4189

Debconf is a great tool but it is often poorly used. Many common mistakes

4190

are listed in the <manref name="debconf-devel" section="7"> man page.

4191

It is something that you must read if you decide to use debconf.

4192

Also, we document some best practices here.

4193

4194

These guidelines include some writing style and typography

4195

recommendations, general considerations about debconf usage as well as

4196

more specific recommendations for some parts of the distribution (the

4197

installation system for instance).

4198

4199

<sect1>Do not abuse debconf

4200

4201

Since debconf appeared in Debian, it has been widely abused and

4202

several criticisms received by the Debian distribution come from

4203

debconf abuse with the need of answering a wide bunch of questions

4204

before getting any little thing installed.

4205

4206

Keep usage notes to what they belong: the NEWS.Debian, or

4207

README.Debian file. Only use notes for important notes which may

4208

directly affect the package usability. Remember that notes will always

4209

block the install until confirmed or bother the user by email.

4210

4211

Carefully choose the questions priorities in maintainer scripts. See

4212

<manref name="debconf-devel" section="7"> for details about priorities.

4213

Most questions should use medium and low priorities.

4214

4215

<sect1>General recommendations for authors and translators

4216

4217

<sect2>Write correct English

4218

4219

Most Debian package maintainers are not native English speakers. So,

4220

writing properly phrased templates may not be easy for them.

4221

4222

Please use (and abuse) &email-debian-l10n-english; mailing

4223

list. Have your templates proofread.

4224

4225

Badly written templates give a poor image of your package, of your

4226

work...or even of Debian itself.

4227

4228

Avoid technical jargon as much as possible. If some terms sound common

4229

to you, they may be impossible to understand for others. If you cannot

4230

avoid them, try to explain them (use the extended description). When

4231

doing so, try to balance between verbosity and simplicity.

4232

4233

<sect2>Be kind to translators

4234

4235

Debconf templates may be translated. Debconf, along with its sister

4236

package <prgn>po-debconf</prgn> offers a simple framework for getting

4237

templates translated by translation teams or even individuals.

4238

4239

Please use gettext-based templates. Install <package>po-debconf</package> on your

4240

development system and read its documentation ("man po-debconf" is a

4241

good start).

4242

4243

Avoid changing templates too often. Changing templates text induces

4244

more work to translators which will get their translation "fuzzied". If

4245

you plan changes to your original templates, please contact

4246

translators. Most active translators are very responsive and getting

4247

their work included along with your modified templates will save you

4248

additional uploads. If you use gettext-based templates, the

4249

translator's name and e-mail addresses are mentioned in the po files

4250

headers.

4251

4252

The use of the <prgn>podebconf-report-po</prgn> from the

4253

po-debconf package is highly recommended to warn translators which

4254

have incomplete translations and request them for updates.

4255

4256

If in doubt, you may also contact the translation team for a given

4257

language (debian-l10n-xxxxx@lists.debian.org), or the

4258

&email-debian-i18n; mailing list.

4259

4260

Calls for translations posted to

4261

&email-debian-i18n; with the <file>debian/po/templates.pot</file> file

4262

attached or referenced in a URL are encouraged. Be sure to mentions in

4263

these calls for new translations which languages you have existing

4264

translations for, in order to avoid duplicate work.

4265

<sect2>Unfuzzy complete translations when correcting typos and spelling

4266

4267

4268

When the text of a debconf template is corrected and you are

4269

sure that the change does not affect

4270

translations, please be kind to translators and unfuzzy their

4271

translations.

4272

4273

If you don't do so, the whole template will not be translated as long

4274

as a translator will send you an update.

4275

4276

To unfuzzy translations, you can proceed the following way:

4277

4278

<item>

4279

Put all incomplete PO files out of the way. You can check the

4280

completeness by using (needs the <package>gettext</package> package installed):

4281

<example>for i in debian/po/*po; do echo -n $i: ; msgfmt -o /dev/null

4282

--statistics $i; done</example>

4283

<item>

4284

move all files which report either fuzzy strings to a temporary

4285

place. Files which report no fuzzy strings (only translated and

4286

untranslated) will be kept in place.

4287

<item>

4288

now and now only, modify the template for the typos

4289

and check again that translation are not impacted (typos, spelling

4290

errors, sometimes typographical corrections are usually OK)

4291

<item>

4292

run <prgn>debconf-updatepo</prgn>. This will fuzzy all strings

4293

you modified in translations. You can see this by running the above

4294

again

4295

<item>

4296

use the following command:

4297

<example>for i in debian/po/*po; do msgattrib --output-file=$i --clear-fuzzy $i; done</example>

4298

<item>

4299

move back to debian/po the files which showed fuzzy strings in the first step

4300

<item>

4301

run <prgn>debconf-updatepo</prgn> again

4302

</enumlist>

4303

<sect2>Do not make assumptions about interfaces

4304

4305

Templates text should not make reference to widgets belonging to some

4306

debconf interfaces. Sentences like "If you answer Yes..." have no

4307

meaning for users of graphical interfaces which use checkboxes for

4308

boolean questions.

4309

4310

String templates should also avoid mentioning the default values in

4311

their description. First, because this is redundant with the values

4312

seen by the users. Also, because these default values may be different

4313

from the maintainer choices (for instance, when the debconf database

4314

was preseeded).

4315

4316

More generally speaking, try to avoid referring to user actions.

4317

Just give facts.

4318

4319

<sect2>Do not use first person

4320

4321

You should avoid the use of first person ("I will do this..." or "We

4322

recommend..."). The computer is not a person and the Debconf templates

4323

do not speak for the Debian developers. You should use neutral

4324

construction and often the passive form. Those of you who already

4325

wrote scientific publications, just write your templates like you

4326

would write a scientific paper.

4327

4328

<sect2>Be gender neutral

4329

4330

The world is made of men and women. Please use gender-neutral

4331

constructions in your writing. This is not Political Correctness, this

4332

is showing respect to all humanity.

4333

4334

4335

<sect1>Templates fields definition

4336

4337

This part gives some information which is mostly taken from the

4338

<manref name="debconf-devel" section="7"> manual page.

4339

4340

<sect2>Type

4341

4342

4343

<sect3>string:

4344

4345

Results in a free-form input field that the user can type any string into.

4346

4347

<sect3>password:

4348

4349

Prompts the user for a password. Use this with caution; be aware that

4350

the password the user enters will be written to debconf's

4351

database. You should probably clean that value out of the database as

4352

soon as is possible.

4353

4354

<sect3>boolean:

4355

4356

A true/false choice. Remember: true/false, not yes/no...

4357

4358

<sect3>select:

4359

4360

A choice between one of a number of values. The choices must be

4361

specified in a field named 'Choices'. Separate the possible values

4362

with commas and spaces, like this: Choices: yes, no, maybe

4363

4364

<sect3>multiselect:

4365

4366

Like the select data type, except the user can choose any number of

4367

4368

items from the choices list (or chose none of them).

4369

4370

<sect3>note:

4371

4372

Rather than being a question per se, this datatype indicates a note

4373

that can be displayed to the user. It should be used only for

4374

important notes that the user really should see, since debconf will go

4375

to great pains to make sure the user sees it; halting the install for

4376

them to press a key, and even mailing the note to them in some

4377

cases.

4378

4379

<sect3>text:

4380

4381

This type is now considered obsolete: don't use it.

4382

4383

<sect3>error:

4384

4385

THIS TEMPLATE TYPE IS NOT HANDLED BY DEBCONF YET.

4386

4387

It has been added to cdebconf, the C version of debconf, first used in

4388

the Debian Installer.

4389

4390

Please do not use it unless debconf supports it.

4391

4392

This type is designed to handle error message. It is mostly similar to

4393

the "note" type. Frontends may present it differently (for instance,

4394

the dialog frontend of cdebconf draws a red screen instead of the

4395

usual blue one).

4396

4397

4398

<sect2>Description: short and extended description

4399

4400

Template descriptions have two parts: short and extended. The short

4401

description is in the "Description:" line of the template.

4402

4403

The short description should be kept short (50 characters or so) so

4404

that it may be accomodated by most debconf interfaces. Keeping it

4405

short also helps translators, as usually translations tend to end up

4406

being longer than the original.

4407

4408

The short description should be able to stand on its own. Some

4409

interfaces do not show the long description by default, or only if the

4410

user explicitely asks for it or even do not show it at all. Avoid

4411

things like "What do you want to do?"

4412

4413

The short description does not necessarily have to be a full

4414

sentence. This is part of the "keep it short and efficient"

4415

recommendation.

4416

4417

The extended description should not repeat the short description word

4418

for word. If you can't think up a long description, then first, think

4419

some more. Post to debian-devel. Ask for help. Take a writing class!

4420

That extended description is important. If after all that you still

4421

can't come up with anything, leave it blank.

4422

4423

The extended description should use complete sentences. Paragraphs

4424

should be kept short for improved readability. Do not mix two ideas

4425

in the same paragraph but rather use another paragraph.

4426

4427

Don't be too verbose. User tend to ignore too long screens.

4428

20 lines are by experience a border you shouldn't cross,

4429

because that means that in the classical dialog interface,

4430

people will need to scroll, and lot of people just don't do that.

4431

4432

For specific rules depending on templates type (string, boolean,

4433

etc.), please read below.

4434

4435

<sect2>Choices

4436

4437

This field should be used for Select and Multiselect types. It

4438

contains the possible choices which will be presented to users. These

4439

choices should be separated by commas.

4440

4441

4442

<sect2>Default

4443

4444

This field is optional. It contains the default answer for string,

4445

select and multiselect templates. For multiselect templates, it may

4446

contain a comma-separated list of choices.

4447

4448

<sect1>Templates fields specific style guide

4449

4450

4451

<sect2>Type field

4452

4453

No specific indication except: use the appropriate type by referring

4454

to the previous section.

4455

4456

<sect2>Description field

4457

4458

Below are specific instructions for properly writing the Description

4459

(short and extended) depending on the template type.

4460

4461

<sect3>String/password templates

4462

4463

<list>

4464

<item> The short description is a prompt and not a title. Avoid

4465

question style prompts ("IP Address?") in favour of

4466

"opened" prompts ("IP address:").

4467

The use of colons is recommended.

4468

4469

<item> The extended description is a complement to the short description.

4470

In the extended part, explain what is being asked, rather than ask

4471

the same question again using longer words. Use complete sentences.

4472

Terse writing style is strongly discouraged.

4473

</list>

4474

4475

<sect3>Boolean templates

4476

4477

<list>

4478

<item> The short description should be phrased in the form of a question

4479

which should be kept short and should generally end with a question

4480

mark. Terse writing style is permitted and even encouraged if the

4481

question is rather long (remember that translations are often longer

4482

than original versions)

4483

4484

<item> The extended description should not include a question.

4485

4486

<item> Again, please avoid referring to specific interface widgets. A common

4487

mistake for such templates is "if you answer Yes"-type

4488

constructions.

4489

</list>

4490

4491

<sect3>Select/Multiselect

4492

4493

<list>

4494

<item> The short description is a prompt and not a title.

4495

Do not use useless

4496

"Please choose..." constructions. Users are clever enough to figure

4497

out they have to choose something...:)

4498

4499

<item> The extended description will complete the short description. It may

4500

refer to the available choices. It may also mention that the user

4501

may choose more than one of the available choices, if the template

4502

is a multiselect one (although the interface often makes this

4503

clear).

4504

</list>

4505

4506

<sect3>Notes

4507

4508

<list>

4509

<item> The short description should be considered to be a *title*.

4510

4511

<item> The extended description is what will be displayed as a more detailed

4512

explanation of the note. Phrases, no terse writing style.

4513

4514

<item> Do not abuse debconf.

4515

Notes are the most common way to abuse

4516

debconf. As written in debconf-devel manual page: it's best to use them

4517

only for warning about very serious problems. The NEWS.Debian or

4518

README.Debian files are the appropriate location for a lot of notes.

4519

If, by reading this, you consider converting your Note type templates

4520

to entries in NEWS/Debian or README.Debian, plus consider keeping existing

4521

translations for the future.

4522

</list>

4523

4524

4525

<sect2>Choices field

4526

4527

If the Choices are likely to change often, please consider using the

4528

"__Choices" trick. This will split each individual choice into a

4529

single string, which will considerably help translators for doing

4530

their work.

4531

4532

<sect2>Default field

4533

4534

If the default value, for a "select" template, is likely to vary

4535

depending on the user language (for instance, if the choice is a

4536

language choice), please use the "_DefaultChoice" trick.

4537

4538

This special field allow translators to put the most appropriate

4539

choice according to their own language. It will become the default

4540

choice when their language is used while your own mentioned Default

4541

Choice will be used chan using English.

4542

4543

Example, taken from the geneweb package templates:

4544

4545

Template: geneweb/lang

4546

Type: select

4547

__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)

4548

# This is the default choice. Translators may put their own language here

4549

# instead of the default.

4550

# WARNING : you MUST use the ENGLISH FORM of your language

4551

# For instance, the french translator will need to put "French (fr)" here.

4552

_DefaultChoice: English (en)[ translators, please see comment in PO files]

4553

_Description: Geneweb default language:

4554

</example>

4555

4556

Note the use of brackets which allow internal comments in debconf

4557

fields. Also note the use of comments which will show up in files the

4558

translators will work with.

4559

4560

The comments are needed as the DefaultChoice trick is a bit

4561

confusing: the translators may put their own choice

4562

4563

<sect2>Default field

4564

4565

Do NOT use empty default field. If you don't want to use default

4566

values, do not use Default at all.

4567

4568

If you use po-debconf (and you should, see 2.2), consider making this

4569

field translatable, if you think it may be translated.

4570

4571

If the default value may vary depending on language/country (for

4572

instance the default value for a language choice), consider using the

4573

special "_DefaultChoice" type documented in <manref name="po-debconf" section="7">).

4574

</sect>

4575

4576

4577

4578

<heading>Internationalization</heading>

4579

4580

4581

<heading>Handling debconf translations</heading>

4582

4583

Like porters, translators have a difficult task. They work on many

4584

packages and must collaborate with many different

4585

maintainers. Moreover, most of the time, they are not native English

4586

speakers, so you may need to be particularly patient with them.

4587

4588

The goal of <package>debconf</package> was to make packages

4589

configuration easier for maintainers and for users. Originally,

4590

translation of debconf templates was handled with

4591

<prgn>debconf-mergetemplate</prgn>. However, that technique is now

4592

deprecated; the best way to accomplish <package>debconf</package>

4593

internationalization is by using the <package>po-debconf</package>

4594

package. This method is easier both for maintainer and translators;

4595

transition scripts are provided.

4596

4597

Using <package>po-debconf</package>, the translation is stored in

4598

<file>po</file> files (drawing from <prgn>gettext</prgn> translation

4599

techniques). Special template files contain the original messages and

4600

mark which fields are translatable. When you change the value of a

4601

translatable field, by calling <prgn>debconf-updatepo</prgn>, the

4602

translation is marked as needing attention from the translators. Then,

4603

at build time, the <prgn>dh_installdebconf</prgn> program takes care

4604

of all the needed magic to add the template along with the up-to-date

4605

translations into the binary packages. Refer to the <manref

4606

name="po-debconf" section="7"> manual page for details.

4607

</sect1>

4608

4609

4610

<heading>Internationalized documentation</heading>

4611

4612

Internationalizing documentation is crucial for users, but a lot of

4613

labor. There's no way to eliminate all that work, but you can make things

4614

easier for translators.

4615

4616

If you maintain documentation of any size, its easier for translators

4617

if they have access to a source control system. That lets translators

4618

see the differences between two versions of the documentation, so, for

4619

instance, they can see what needs to be retranslated. It is

4620

recommended that the translated documentation maintain a note about

4621

what source control revision the translation is based on. An

4622

interesting system is provided by <url id="&url-i18n-doc-check;"

4623

name="doc-check"> in the <package>boot-floppies</package> package,

4624

which shows an overview of the translation status for any given

4625

language, using structured comments for the current revision of the

4626

file to be translated and, for a translated file, the revision of the

4627

original file the translation is based on. You might wish to adapt

4628

and provide that in your CVS area.

4629

4630

If you maintain XML or SGML documentation, we suggest that you isolate

4631

any language-independent information and define those as entities in a

4632

separate file which is included by all the different

4633

translations. This makes it much easier, for instance, to keep URLs

4634

up to date across multiple files.

4635

</sect1>

4636

</sect>

4637

4638

4639

<heading>Common packaging situations</heading>

4640

4641

<!--

4642

<sect1 id="bpp-kernel">Kernel modules/patches

4643

4644

&FIXME; Heavy use of kernel-package. provide files in

4645

/etc/modutils/ for module configuration.

4646

-->

4647

4648

4649

<heading>Packages using

4650

<prgn>autoconf</prgn>/<prgn>automake</prgn></heading>

4651

4652

Keeping <prgn>autoconf</prgn>'s <file>config.sub</file> and

4653

<file>config.guess</file> files up to date is critical for porters,

4654

especially on more volatile architectures. Some very good packaging

4655

practices for any package using <prgn>autoconf</prgn> and/or

4656

<prgn>automake</prgn> have been synthesized in

4657

&file-bpp-autotools; from the <package>autotools-dev</package>

4658

package. You're strongly encouraged to read this file and

4659

to follow the given recommendations.

4660

4661

4662

<sect1 id="bpp-libraries">Libraries

4663

4664

Libraries are always difficult to package for various reasons. The policy

4665

imposes many constraints to ease their maintenance and to make sure

4666

upgrades are as simple as possible when a new upstream version comes out.

4667

Breakage in a library can result in dozens of dependent packages

4668

breaking.

4669

4670

Good practices for library packaging have been grouped in

4671

<url id="&url-libpkg-guide;" name="the library packaging guide">.

4672

4673

4674

<sect1 id="bpp-docs">Documentation

4675

4676

Be sure to follow the <url id="&url-debian-policy;ch-docs.html"

4677

name="Policy on documentation">.

4678

4679

If your package contains documentation built from XML or SGML, we

4680

recommend you not ship the XML or SGML source in the binary

4681

package(s). If users want the source of the documentation, they

4682

should retrieve the source package.

4683

4684

Policy specifies that documentation should be shipped in HTML format.

4685

We also recommend shipping documentation in PDF and plain text format if

4686

convenient and if output of reasonable quality is possible. However, it is generally

4687

not appropriate to ship plain text versions of documentation whose source

4688

format is HTML.

4689

4690

Major shipped manuals should register themselves with

4691

<package>doc-base</package> on installation. See the

4692

<package>doc-base</package> package documentation for more

4693

information.

4694

4695

4696

<sect1 id="bpp-other">Specific types of packages

4697

4698

Several specific types of packages have special sub-policies and

4699

corresponding packaging rules and practices:

4700

<list>

4701

<item>

4702

Perl related packages have a <url name="Perl policy"

4703

id="&url-perl-policy;">, some examples of packages following that

4704

policy are <package>libdbd-pg-perl</package> (binary perl module) or

4705

<package>libmldbm-perl</package> (arch independent perl module).

4706

<item>

4707

Python related packages have their python policy; see

4708

&file-python-policy; in the <package>python</package> package.

4709

<item>

4710

Emacs related packages have the <url id="&url-emacs-policy;"

4711

name="emacs policy">.

4712

<item>

4713

Java related packages have their <url id="&url-java-policy;"

4714

name="java policy">.

4715

<item>

4716

Ocaml related packages have their own policy, found in

4717

&file-ocaml-policy; from the <package>ocaml</package> package. A good

4718

example is the <package>camlzip</package> source package.

4719

<item>

4720

Packages providing XML or SGML DTDs should conform to the

4721

recommendations found in the <package>sgml-base-doc</package>

4722

package.

4723

<item>

4724

Lisp packages should register themselves with

4725

<package>common-lisp-controller</package>, about which see

4726

&file-lisp-controller;.

4727

4728

</list>

4729

</sect1>

4730

4731

<!--

4732

<sect1 id="custom-config-files">Custom configuration files

4733

4734

&FIXME; speak of "ucf", explain solution with a template,

4735

explain conf.d directories

4736

4737

<sect1 id="config-with-db">Use of an external database

4738

4739

&FIXME; The software may require a database that you need to setup.

4740

But the database may be local or distant. Thus you can't depend

4741

on a database server but just on the corresponding library.

4742

4743

sympa may be an example package

4744

-->

4745

4746

4747

<heading>Architecture-independent data</heading>

4748

4749

It is not uncommon to have a large amount of architecture-independent

4750

data packaged with a program. For example, audio files, a collection

4751

of icons, wallpaper patterns, or other graphic files. If the size of

4752

this data is negligible compared to the size of the rest of the

4753

package, it's probably best to keep it all in a single package.

4754

4755

However, if the size of the data is considerable, consider splitting

4756

it out into a separate, architecture-independent package ("_all.deb").

4757

By doing this, you avoid needless duplication of the same data into

4758

eleven or more .debs, one per each architecture. While this

4759

adds some extra overhead into the <file>Packages</file> files, it

4760

saves a lot of disk space on Debian mirrors. Separating out

4761

architecture-independent data also reduces processing time of

4762

<prgn>lintian</prgn> or <prgn>linda</prgn> (see <ref id="tools-lint">)

4763

when run over the entire Debian archive.

4764

</sect1>

4765

4766

4767

4768

<heading>Needing a certain locale during build</heading>

4769

4770

If you need a certain locale during build, you can create a temporary

4771

file via this trick:

4772

4773

If you set LOCPATH to the equivalent of /usr/lib/locale, and LC_ALL to

4774

the name of the locale you generate, you should get what you want

4775

without being root. Something like this:

4776

4777

4778

LOCALE_PATH=debian/tmpdir/usr/lib/locale

4779

LOCALE_NAME=en_IN

4780

LOCALE_CHARSET=UTF-8

4781

4782

mkdir -p $LOCALE_PATH

4783

localedef -i "$LOCALE_NAME.$LOCALE_CHARSET" -f "$LOCALE_CHARSET" "$LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET"

4784

4785

# Using the locale

4786

LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date

4787

</example>

4788

</sect1>

4789

4790

4791

<heading>Make transition packages deborphan compliant</heading>

4792

4793

Deborphan is a program for helping users to detect which packages can safely be

4794

removed from the system, i.e. the ones that have no packages depending on

4795

them. The default operation is to search only within the libs and oldlibs

4796

sections, to hunt down unused libraries. But when passed the right argument,

4797

it tries to catch other useless packages.

4798

4799

For example, with --guess-dummy, deborphan tries to search all transitional packages

4800

which were needed for upgrade but which can now safely be removed. For that,

4801

it looks for the string "dummy" or "transitional" in their short

4802

description.

4803

4804

So, when you are creating such a package, please make sure to add this text

4805

to your short description. If you are looking for examples, just run:

4806

<example>apt-cache search .|grep dummy</example> or

4807

<example>apt-cache search .|grep transitional</example>.

4808

</sect1>

4809

4810

4811

4812

<heading>Best practices for <file>orig.tar.gz</file> files</heading>

4813

4814

There are two kinds of original source tarballs: Pristine source

4815

and repackaged upstream source.

4816

4817

4818

<heading>Pristine source</heading>

4819

4820

The defining characteristic of a pristine source tarball is that the

4821

.orig.tar.gz file is byte-for-byte identical to a tarball officially

4822

distributed by the upstream author.

4823

4824

We cannot prevent upstream authors from changing the tarball

4825

they distribute without also incrementing the version number, so

4826

there can be no guarantee that a pristine tarball is identical

4827

to what upstream currently distributing at any point in

4828

time. All that can be expected is that it is identical to

4829

something that upstream once did distribute.

4830

4831

If a difference arises later (say, if upstream notices that he wasn't

4832

using maximal comression in his original distribution and then

4833

re-<tt>gzip</tt>s it), that's just too bad. Since there is no good way

4834

to upload a new .orig.tar.gz for the same version, there is not even

4835

any point in treating this situation as a bug.

4836

</footnote>

4837

This makes it possible to use checksums to easily verify that all

4838

changes between Debian's version and upstream's are contained in the

4839

Debian diff. Also, if the original source is huge, upstream authors

4840

and others who already have the upstream tarball can save download

4841

time if they want to inspect your packaging in detail.

4842

4843

4844

There is no universally accepted guidelines that upstream authors

4845

follow regarding to the directory structure inside their tarball, but

4846

<prgn>dpkg-source</prgn> is nevertheless able to deal with most

4847

upstream tarballs as pristine source. Its strategy is equivalent to

4848

the following:

4849

4850

4851

4852

<item>

4853

It unpacks the tarball in an empty temporary directory by doing

4854

4855

4856

zcat path/to/<packagename>_<upstream-version>.orig.tar.gz | tar xf -

4857

</example>

4858

</item>

4859

<item>

4860

If, after this, the temporary directory contains nothing but one

4861

directory and no other files, <prgn>dpkg-source</prgn> renames that

4862

directory to

4863

<tt><packagename>-<upstream-version>(.orig)</tt>. The name

4864

of the top-level directory in the tarball does not matter, and is

4865

forgotten.

4866

</item>

4867

<item>

4868

Otherwise, the upstream tarball must have been packaged without a

4869

common top-level directory (shame on the upstream author!). In this

4870

case, <prgn>dpkg-source</prgn> renames the temporary directory

4871

itself to

4872

<tt><packagename>-<upstream-version>(.orig)</tt>.

4873

</item>

4874

</enumlist>

4875

4876

</sect2>

4877

4878

<heading>Repackaged upstream source</heading>

4879

4880

You should upload packages with a pristine source

4881

tarball if possible, but there are various reasons why it might not be

4882

possible. This is the case if upstream does not distribute the source

4883

as gzipped tar at all, or if upstream's tarball contains non-DFSG-free

4884

material that you must remove before uploading.

4885

4886

4887

In these cases the developer must construct a suitable .orig.tar.gz

4888

file himself. We refer to such a tarball as a "repackaged upstream

4889

source". Note that a "repackaged upstream source" is different from a

4890

Debian-native package. A repackaged source still comes with

4891

Debian-specific changes in a separate <tt>.diff.gz</tt> and still has

4892

a version number composed of <tt><upstream-version></tt> and

4893

<tt><debian-revision></tt>.

4894

4895

4896

There may be cases where it is desirable to repackage the source even

4897

though upstream distributes a <tt>.tar.gz</tt> that could in principle

4898

be used in its pristine form. The most obvious is if

4899

significant space savings can be achieved by recompressing

4900

the tar archive or by removing genuinely useless cruft from the

4901

upstream archive. Use your own discretion here, but be prepared to

4902

defend your decision if you repackage source that could have been

4903

pristine.

4904

4905

4906

A repackaged .orig.tar.gz

4907

4908

4909

4910

<item>

4911

4912

must contain detailed information how

4913

the repackaged source was obtained, and how this can be reproduced, in

4914

<file>README.Debian-source</file> or a similar file. This file should

4915

be in the <file>diff.gz</file> part of the Debian source package,

4916

usually in the <file>debian</file> directory, not in the

4917

repackaged <file>orig.tar.gz</file>. It is also a good idea to provide a

4918

<tt>get-orig-source</tt> target in your <file>debian/rules</file> file

4919

that repeats the process, as described in the Policy Manual, <url

4920

id="&url-debian-policy;ch-source.html#s-debianrules" name="Main

4921

building script: debian/rules">.

4922

4923

</item>

4924

<item>

4925

should not contain any file that does not come from the

4926

upstream author(s), or whose contents has been changed by you.

4927

4928

As a special exception, if the omission of non-free files would lead

4929

to the source failing to build without assistance from the Debian

4930

diff, it might be appropriate to instead edit the files, omitting only

4931

the non-free parts of them, and/or explain the situation in a

4932

README.Debian-source  file in the root of the source

4933

tree. But in that case please also urge the upstream author to make

4934

the non-free components easier seperable from the rest of the source.

4935

</footnote>

4936

</item>

4937

<item>

4938

4939

should, except where impossible for legal reasons,

4940

preserve the entire building and portablility infrastructure provided

4941

by the upstream author. For example, it is not a sufficient reason for

4942

omitting a file that it is used only when building on

4943

MS-DOS. Similarly, a Makefile provided by upstream should not be

4944

omitted even if the first thing your <file>debian/rules</file> does is

4945

to overwrite it by running a configure script.

4946

4947

4948

(Rationale: It is common for Debian users who need to build

4949

software for non-Debian platforms to fetch the source from a Debian

4950

mirror rather than trying to locate a canonical upstream distribution

4951

point).

4952

</item>

4953

<item>

4954

should use

4955

<tt><packagename>-<upstream-version>.orig</tt> as the name

4956

of the top-level directory in its tarball. This makes it possible to

4957

distinguish pristine tarballs from repackaged ones.

4958

</item>

4959

<item>

4960

should be gzipped with maximal compression.

4961

</item>

4962

</enumlist>

4963

4964

4965

The canonical way to meet the latter two points is to let

4966

<tt>dpkg-source -b</tt> construct the repackaged tarball from an

4967

unpacked directory.

4968

4969

</sect2>

4970

4971

<heading>Changing binary files in <tt>diff.gz</tt></heading>

4972

4973

Sometimes it is necessary to change binary files contained in the

4974

original tarball, or to add binary files that are not in it.

4975

If this is done by simply copying the files into the debianized source

4976

tree, <prgn>dpkg-source</prgn> will not be able to handle this. On the

4977

other hand, according to the guidelines given above, you cannot

4978

include such a changed binary file in a repackaged

4979

<file>orig.tar.gz</file>. Instead, include the file in the

4980

<file>debian</file> directory in <prgn>uuencode</prgn>d (or similar)

4981

form

4982

4983

The file should have a name that makes it clear which binary file it

4984

encodes. Usually, some postfix indicating the encoding should be

4985

appended to the original filename.

4986

Note that you don't need to depend on <package>sharutils</package> to get

4987

the <prgn>uudecode</prgn> program if you use <prgn>perl</prgn>'s

4988

<tt>pack</tt> function.

4989

The code could look like

4990

4991

uuencode-file:

4992

perl -ne 'print(pack "u", $$_);' $(file) > $(file).uuencoded

4993

4994

uudecode-file:

4995

perl -ne 'print(unpack "u", $$_);' $(file).uuencoded > $(file)

4996

</example>

4997

</footnote>.

4998

The file would then be decoded and copied to its place during the

4999

build process. Thus the change will be visible quite easy.

5000

5001

5002

Some packages use <prgn>dbs</prgn> to manage patches to their upstream

5003

source, and always create a new <tt>orig.tar.gz</tt> file that

5004

contains the real <tt>orig.tar.gz</tt> in its toplevel directory. This

5005

is questionable with respect to the preference for pristine source. On

5006

the other hand, it is easy to modify or add binary files in this case:

5007

Just put them into the newly created <tt>orig.tar.gz</tt> file,

5008

besides the real one, and copy them to the right place during the

5009

build process.

5010

5011

</sect2>

5012

</sect1>

5013

5014

5015

</sect>

5016

</chapt>

5017

5018

5019

5020

<heading>Beyond Packaging</heading>

5021

5022

Debian is about a lot more than just packaging software and

5023

maintaining those packages. This chapter contains information about

5024

ways, often really critical ways, to contribute to Debian beyond

5025

simply creating and maintaining packages.

5026

5027

As a volunteer organization, Debian relies on the discretion of its

5028

members in choosing what they want to work on and in choosing

5029

the most critical thing to spend their time on.

5030

5031

5032

<heading>Bug reporting</heading>

5033

5034

We encourage you to file bugs as you find them in Debian packages. In

5035

fact, Debian developers are often the first line testers. Finding and

5036

reporting bugs in other developers' packages improves the quality of

5037

Debian.

5038

5039

Read the <url name="instructions for reporting bugs"

5040

id="&url-bts-report;"> in the Debian <url name="bug tracking system"

5041

id="&url-bts;">.

5042

5043

Try to submit the bug from a normal user account at which you are

5044

likely to receive mail, so that people can reach you if they need

5045

further information about the bug. Do not submit bugs as root.

5046

5047

You can use a tool like <manref name="reportbug" section="1"> to

5048

submit bugs. It can automate and generally ease the process.

5049

5050

Make sure the bug is not already filed against a package.

5051

Each package has a bug list easily reachable at

5052

<tt>http://&bugs-host;/<var>packagename</var></tt>

5053

Utilities like <manref name="querybts" section="1"> can also

5054

provide you with this information (and <prgn>reportbug</prgn>

5055

will usually invoke <prgn>querybts</prgn> before sending, too).

5056

5057

Try to direct your bugs to the proper location. When for example

5058

your bug is about a package which overwrites files from another package,

5059

check the bug lists for both of those packages in order to

5060

avoid filing duplicate bug reports.

5061

5062

For extra credit, you can go through other packages, merging bugs

5063

which are reported more than once, or tagging bugs `fixed'

5064

when they have already been fixed. Note that when you are

5065

neither the bug submitter nor the package maintainer, you should

5066

not actually close the bug (unless you secure permission from the

5067

maintainer).

5068

5069

From time to time you may want to check what has been going on

5070

with the bug reports that you submitted. Take this opportunity to

5071

close those that you can't reproduce anymore. To find

5072

out all the bugs you submitted, you just have to visit

5073

<tt>http://&bugs-host;/from:<var><your-email-addr></var></tt>.

5074

5075

<sect1 id="submit-many-bugs">Reporting lots of bugs at once (mass bug filing)

5076

5077

Reporting a great number of bugs for the same problem on a great

5078

number of different packages — i.e., more than 10 — is a deprecated

5079

practice. Take all possible steps to avoid submitting bulk bugs at

5080

all. For instance, if checking for the problem can be automated, add

5081

a new check to <package>lintian</package> so that an error or warning

5082

is emitted.

5083

5084

If you report more than 10 bugs on the same topic at once, it is

5085

recommended that you send a message to &email-debian-devel; describing

5086

your intention before submitting the report, and mentioning the

5087

fact in the subject of your mail. This will allow other

5088

developers to verify that the bug is a real problem. In addition, it

5089

will help prevent a situation in which several maintainers start

5090

filing the same bug report simultaneously.

5091

5092

Please use the programms <prgn>dd-list</prgn> and

5093

if appropriate <prgn>whodepends</prgn>

5094

(from the package devscripts)

5095

to generate a list of all affected packages, and include the

5096

output in your mail to &email-debian-devel;.

5097

5098

Note that when sending lots of bugs on the same subject, you should

5099

send the bug report to <email>maintonly@&bugs-host;</email> so

5100

that the bug report is not forwarded to the bug distribution mailing

5101

list.

5102

5103

5104

<sect id="qa-effort">Quality Assurance effort

5105

5106

<sect1 id="qa-daily-work">Daily work

5107

5108

Even though there is a dedicated group of people for Quality

5109

Assurance, QA duties are not reserved solely for them. You can

5110

participate in this effort by keeping your packages as bug-free as

5111

possible, and as lintian-clean (see <ref id="lintian">) as

5112

possible. If you do not find that possible, then you should consider

5113

orphaning some of your packages (see <ref

5114

id="orphaning">). Alternatively, you may ask the help of other people

5115

in order to catch up with the backlog of bugs that you have (you can ask

5116

for help on &email-debian-qa; or &email-debian-devel;). At the same

5117

time, you can look for co-maintainers (see <ref id="collaborative-maint">).

5118

5119

<sect1 id="qa-bsp">Bug squashing parties

5120

5121

From time to time the QA group organizes bug squashing parties to get rid of

5122

as many problems as possible. They are announced on &email-debian-devel-announce;

5123

and the announcement explains which area will be the focus of the party:

5124

usually they focus on release critical bugs but it may happen that they

5125

decide to help finish a major upgrade (like a new perl version

5126

which requires recompilation of all the binary modules).

5127

5128

The rules for non-maintainer uploads differ during the parties because

5129

the announcement of the party is considered prior notice for NMU. If

5130

you have packages that may be affected by the party (because they have

5131

release critical bugs for example), you should send an update to each of

5132

the corresponding bug to explain their current status and what you expect

5133

from the party. If you don't want an NMU, or if you're only interested in a

5134

patch, or if you will deal yourself with the bug, please explain that in

5135

the BTS.

5136

5137

People participating in the party have special rules for NMU, they can

5138

NMU without prior notice if they upload their NMU to

5139

DELAYED/3-day at least. All other NMU rules apply as usually; they

5140

should send the patch of the NMU to the BTS (to one of the open bugs

5141

fixed by the NMU, or to a new bug, tagged fixed). They should

5142

also respect any particular wishes of the maintainer.

5143

5144

If you don't feel confident about doing an NMU, just send a patch

5145

to the BTS. It's far better than a broken NMU.

5146

5147

5148

<sect id="contacting-maintainers">Contacting other maintainers

5149

5150

During your lifetime within Debian, you will have to contact other

5151

maintainers for various reasons. You may want to discuss a new

5152

way of cooperating between a set of related packages, or you may

5153

simply remind someone that a new upstream version is available

5154

and that you need it.

5155

5156

Looking up the email address of the maintainer for the package can be

5157

distracting. Fortunately, there is a simple email alias,

5158

<tt><package>@&packages-host;</tt>, which provides a way to

5159

email the maintainer, whatever their individual email address (or

5160

addresses) may be. Replace <tt><package></tt> with the name of

5161

a source or a binary package.

5162

5163

You may also be interested in contacting the persons who are

5164

subscribed to a given source package via <ref id="pkg-tracking-system">.

5165

You can do so by using the <tt><package>@&pts-host;</tt>

5166

email address.

5167

5168

5169

<sect id="mia-qa">Dealing with inactive and/or unreachable maintainers

5170

5171

If you notice that a package is lacking maintenance, you should

5172

make sure that the maintainer is active and will continue to work on

5173

their packages. It is possible that they are not active any more, but

5174

haven't registered out of the system, so to speak. On the other hand,

5175

it is also possible that they just need a reminder.

5176

5177

There is a simple system (the MIA database) in which information about

5178

maintainers who are deemed Missing In Action is recorded.

5179

When a member of the

5180

QA group contacts an inactive maintainer or finds more information about

5181

one, this is recorded in the MIA database. This system is available

5182

in /org/qa.debian.org/mia on the host qa.debian.org, and can be queried

5183

with a tool known as <prgn>mia-query</prgn>.

5184

Use <example>mia-query --help</example> to see how to query the database.

5185

If you find that no information has been recorded

5186

about an inactive maintainer yet, or that you can add more information,

5187

you should generally proceed as follows.

5188

5189

The first step is to politely contact the maintainer,

5190

and wait a reasonable time for a response.

5191

It is quite hard to define "reasonable

5192

time", but it is important to take into account that real life is sometimes

5193

very hectic. One way to handle this would be to send a reminder after two

5194

weeks.

5195

5196

If the maintainer doesn't reply within four weeks (a month), one can

5197

assume that a response will probably not happen. If that happens, you

5198

should investigate further, and try to gather as much useful information

5199

about the maintainer in question as possible. This includes:

5200

5201

<list>

5202

<item>The "echelon" information available through the

5203

<url id="&url-debian-db;" name="developers' LDAP database">,

5204

which indicates when the developer last posted to

5205

a Debian mailing list. (This includes uploads via

5206

debian-*-changes lists.) Also, remember to check whether the

5207

maintainer is marked as "on vacation" in the database.

5208

5209

<item>The number of packages this maintainer is responsible for,

5210

and the condition of those packages. In particular, are there

5211

any RC bugs that have been open for ages? Furthermore, how

5212

many bugs are there in general? Another important piece of

5213

information is whether the packages have been NMUed, and if

5214

so, by whom.

5215

5216

<item>Is there any activity of the maintainer outside of Debian?

5217

For example, they might have posted something recently to

5218

non-Debian mailing lists or news groups.

5219

</list>

5220

5221

A bit of a problem are packages which were sponsored — the maintainer is not

5222

an official Debian developer. The echelon information is not available for

5223

sponsored people, for example, so you need to find and contact the Debian

5224

developer who has actually uploaded the package. Given that they signed the

5225

package, they're responsible for the upload anyhow, and are likely to know what

5226

happened to the person they sponsored.

5227

5228

It is also allowed to post a query to &email-debian-devel;, asking if anyone

5229

is aware of the whereabouts of the missing maintainer.

5230

Please Cc: the person in question.

5231

5232

Once you have gathered all of this, you can contact &email-mia;.

5233

People on this alias will use the information you provide in order to

5234

decide how to proceed. For example, they might orphan one or all of the

5235

packages of the maintainer. If a package has been NMUed, they might prefer

5236

to contact the NMUer before orphaning the package — perhaps the person who

5237

has done the NMU is interested in the package.

5238

5239

One last word: please remember to be polite. We are all volunteers and

5240

cannot dedicate all of our time to Debian. Also, you are not aware of the

5241

circumstances of the person who is involved. Perhaps they might be

5242

seriously ill or might even have died — you do not know who may be on the

5243

receiving side. Imagine how a relative will feel if they read the e-mail

5244

of the deceased and find a very impolite, angry and accusing message!

5245

5246

On the other hand, although we are volunteers, we do have a responsibility.

5247

So you can stress the importance of the greater good — if a maintainer does

5248

not have the time or interest anymore, they should "let go" and give the

5249

package to someone with more time.

5250

5251

If you are interested in working in the MIA team, please have a look at the

5252

README file in /org/qa.debian.org/mia on qa.debian.org where the technical

5253

details and the MIA procedures are documented and contact &email-mia;.

5254

5255

5256

5257

<heading>Interacting with prospective Debian developers</heading>

5258

5259

Debian's success depends on its ability to attract and retain new and

5260

talented volunteers. If you are an experienced developer, we

5261

recommend that you get involved with the process of bringing in new

5262

developers. This section describes how to help new prospective

5263

developers.

5264

5265

5266

<sect1 id="sponsoring">Sponsoring packages

5267

5268

Sponsoring a package means uploading a package for a maintainer who is not

5269

able to do it on their own, a new maintainer applicant. Sponsoring a package

5270

also means accepting responsibility for it.

5271

5272

<!-- FIXME: service down

5273

If you wish to volunteer as a sponsor, you can sign up at <url

5274

id="&url-sponsors;">.

5275

5276

-->

5277

New maintainers usually have certain difficulties creating Debian packages

5278

— this is quite understandable. That is why the sponsor is there, to check

5279

the package and verify that it is good enough for inclusion in Debian.

5280

(Note that if the sponsored package is new, the ftpmasters will also have to

5281

inspect it before letting it in.)

5282

5283

Sponsoring merely by signing the upload or just recompiling is

5284

definitely not recommended. You need to build the source

5285

package just like you would build a package of your own. Remember that it

5286

doesn't matter that you left the prospective developer's name both in the

5287

changelog and the control file, the upload can still be traced to you.

5288

5289

If you are an application manager for a prospective developer, you can also

5290

be their sponsor. That way you can also verify how the applicant is

5291

handling the 'Tasks and Skills' part of their application.

5292

5293

<sect1>Managing sponsored packages

5294

5295

By uploading a sponsored package to Debian, you are certifying that

5296

the package meets minimum Debian standards. That implies that you

5297

must build and test the package on your own system before uploading.

5298

5299

You cannot simply upload a binary <file>.deb</file> from the sponsoree. In

5300

theory, you should only ask for the diff file and the location of the

5301

original source tarball, and then you should download the source and apply

5302

the diff yourself. In practice, you may want to use the source package

5303

built by your sponsoree. In that case, you have to check that they haven't

5304

altered the upstream files in the <file>.orig.tar.gz</file> file that

5305

they're providing.

5306

5307

Do not be afraid to write the sponsoree back and point out changes

5308

that need to be made. It often takes several rounds of back-and-forth

5309

email before the package is in acceptable shape. Being a sponsor

5310

means being a mentor.

5311

5312

Once the package meets Debian standards, build and sign it with

5313

<example>dpkg-buildpackage -k<var>KEY-ID</var></example>

5314

before uploading it to the incoming directory. Of course, you can also

5315

use any part of your <var>KEY-ID</var>, as long as it's unique in your

5316

secret keyring.

5317

5318

The Maintainer field of the <file>control</file> file and the

5319

<file>changelog</file> should list the person who did the packaging, i.e., the

5320

sponsoree. The sponsoree will therefore get all the BTS mail about the

5321

package.

5322

5323

If you prefer to leave a more evident trace of your sponsorship job, you

5324

can add a line stating it in the most recent changelog entry.

5325

5326

You are encouraged to keep tabs on the package you sponsor using

5327

<ref id="pkg-tracking-system">.

5328

5329

<sect1>Advocating new developers

5330

5331

See the page about <url id="&url-newmaint-advocate;"

5332

name="advocating a prospective developer"> at the Debian web site.

5333

5334

<sect1>Handling new maintainer applications

5335

5336

Please see <url id="&url-newmaint-amchecklist;" name="Checklist for

5337

Application Managers"> at the Debian web site.

5338

5339

5340

<chapt id="l10n">Internationalizing, translating, being internationalized

5341

and being translated

5342

5343

Debian supports an ever-increasing number of natural languages. Even if you are

5344

a native English speaker and do not speak any other language, it is part of your

5345

duty as a maintainer to be aware of issues of internationalization (abbreviated

5346

i18n because there are 18 letters between the 'i' and the 'n' in

5347

internationalization). Therefore, even if you are ok with English-only

5348

programs, you should read most of this chapter.

5349

5350

According to <url id="http://www.debian.org/doc/manuals/intro-i18n/"

5351

name="Introduction to i18n"> from Tomohiro KUBOTA, "I18N (internationalization)

5352

means modification of a software or related technologies so that a software can

5353

potentially handle multiple languages, customs, and so on in the world." while

5354

"L10N (localization) means implementation of a specific language for an already

5355

internationalized software."

5356

5357

l10n and i18n are interconnected, but the difficulties related to each of them are very

5358

different. It's not really difficult to allow a program to change the language

5359

in which texts are displayed based on user settings, but it is very time

5360

consuming to actually translate these messages. On the other hand, setting the

5361

character encoding is trivial, but adapting the code to use several character

5362

encodings is a really hard problem.

5363

5364

Setting aside the i18n problems, where no general guideline can be given, there is

5365

actually no central infrastructure for l10n within Debian which could be

5366

compared to the dbuild mechanism for porting. So most of the work has to be

5367

done manually.

5368

5369

5370

<sect id="l10n-handling">How translations are handled within Debian

5371

5372

Handling translation of the texts contained in a package is still a manual

5373

task, and the process depends on the kind of text you want to see translated.

5374

5375

For program messages, the gettext infrastructure is used most of the time.

5376

Most of the time, the translation is handled upstream within projects like the

5377

<url id="http://www.iro.umontreal.ca/contrib/po/HTML/" name="Free Translation

5378

Project">, the <url id="http://developer.gnome.org/projects/gtp/" name="Gnome

5379

translation Project"> or the <url id="http://i18n.kde.org/" name="KDE one">.

5380

The only centralized resource within Debian is the <url

5381

id="http://www.debian.org/intl/l10n/" name="Central Debian translation

5382

statistics">, where you can find some statistics about the translation files

5383

found in the actual packages, but no real infrastructure to ease the translation

5384

process.

5385

5386

An effort to translate the package descriptions started long ago, even if very

5387

little support is offered by the tools to actually use them (i.e., only APT can use

5388

them, when configured correctly). Maintainers don't need to do

5389

anything special to support translated package descriptions;

5390

translators should use the <url id="http://ddtp.debian.org/"

5391

name="DDTP">.

5392

5393

For debconf templates, maintainers should use the po-debconf package to ease the

5394

work of translators, who could use the DDTP to do their work (but the French and

5395

Brazilian teams don't). Some statistics can be found both on the DDTP site

5396

(about what is actually translated), and on the <url

5397

id="http://www.debian.org/intl/l10n/" name="Central Debian translation

5398

statistics"> site (about what is integrated in the packages).

5399

5400

For web pages, each l10n team has access to the relevant CVS, and the statistics

5401

are available from the Central Debian translation statistics site.

5402

5403

For general documentation about Debian, the process is more or less the same

5404

as for the web pages (the translators have access to the CVS), but there are

5405

no statistics pages.

5406

5407

For package-specific documentation (man pages, info documents, other formats),

5408

almost everything remains to be done.

5409

5410

Most notably, the KDE project handles

5411

translation of its documentation in the same way as its program messages.

5412

5413

There is an effort to handle Debian-specific man pages

5414

within a <url

5415

id="http://cvs.debian.org/manpages/?cvsroot=debian-doc" name="specific CVS

5416

repository">.

5417

5418

5419

<sect id="l10n-faqm">I18N & L10N FAQ for maintainers

5420

5421

This is a list of problems that maintainers may face concerning i18n and l10n.

5422

While reading this, keep in mind that there is no real consensus on these

5423

points within Debian, and that this is only advice. If you have a better idea

5424

for a given problem, or if you disagree on some points, feel free to provide

5425

your feedback, so that this document can be enhanced.

5426

5427

<sect1 id="l10n-faqm-tr">How to get a given text translated

5428

5429

To translate package descriptions or debconf templates, you have nothing to do;

5430

the DDTP infrastructure will dispatch the material to translate to volunteers

5431

with no need for interaction from your part.

5432

5433

For all other material (gettext files, man pages, or other documentation), the

5434

best solution is to put your text somewhere on the Internet, and ask on debian-i18n

5435

for a translation in different languages. Some translation team members are

5436

subscribed to this list, and they will take care of the translation and of the

5437

reviewing process. Once they are done, you will get your translated document from them

5438

in your mailbox.

5439

5440

<sect1 id="l10n-faqm-rev">How to get a given translation reviewed

5441

5442

From time to time, individuals translate some texts in your package

5443

and will ask you for inclusion of the translation in the package. This can become problematic if

5444

you are not fluent in the given language. It is a good idea to send the

5445

document to the corresponding l10n mailing list, asking for a review. Once it

5446

has been done, you should feel more confident in the quality of the

5447

translation, and feel safe to include it in your package.

5448

5449

<sect1 id="l10n-faqm-update">How to get a given translation updated

5450

5451

If you have some translations of a given text lying around, each time you

5452

update the original, you should ask the previous translator to update

5453

the translation with your new changes.

5454

Keep in mind that this task takes time; at least one week to get

5455

the update reviewed and all.

5456

5457

If the translator is unresponsive, you may ask for help on the corresponding

5458

l10n mailing list. If everything fails, don't forget to put a warning in the

5459

translated document, stating that the translation is somehow outdated, and that

5460

the reader should refer to the original document if possible.

5461

5462

Avoid removing a translation completely because it is outdated. Old

5463

documentation is often better than no documentation at all for non-English

5464

speakers.

5465

5466

<sect1 id="l10n-faqm-bug">How to handle a bug report concerning a translation

5467

5468

The best solution may be to mark the bug as "forwarded to upstream", and

5469

forward it to both the previous translator and his/her team (using the

5470

corresponding debian-l10n-XXX mailing list).

5471

5472

5473

<sect id="l10n-faqtr">I18N & L10N FAQ for translators

5474

5475

While reading this, please keep in mind that there is no general procedure

5476

within Debian concerning these points, and that in any case, you should

5477

collaborate with your team and the package maintainer.

5478

5479

<sect1 id="l10n-faqtr-help">How to help the translation effort

5480

5481

Choose what you want to translate, make sure that nobody is already working on

5482

it (using your debian-l10n-XXX mailing list), translate it, get it reviewed by

5483

other native speakers on your l10n mailing list, and provide it to the

5484

maintainer of the package (see next point).

5485

5486

<sect1 id="l10n-faqtr-inc">How to provide a translation for inclusion in a package

5487

5488

Make sure your translation is correct (asking for review on your l10n mailing

5489

list) before providing it for inclusion. It will save time for everyone, and

5490

avoid the chaos resulting in having several versions of the same document in

5491

bug reports.

5492

5493

The best solution is to file a regular bug containing the translation against

5494

the package. Make sure to use the 'PATCH' tag, and to not use a severity higher

5495

than 'wishlist', since the lack of translation never prevented a program from

5496

running.

5497

5498

<sect id="l10n-best">Best current practice concerning l10n

5499

5500

<list>

5501

<item>

5502

As a maintainer, never edit the translations in any way (even to reformat the

5503

layout) without asking on the corresponding l10n mailing list. You risk for

5504

example breaksing the encoding of the file by doing so. Moreover, what you

5505

consider an error can be right (or even needed) in the given language.

5506

<item>

5507

As a translator, if you find an error in the original text, make sure to report

5508

it. Translators are often the most attentive readers of a given text, and if

5509

they don't report the errors they find, nobody will.

5510

<item>

5511

In any case, remember that the major issue with l10n is that it requires

5512

several people to cooperate, and that it is very easy to start a flamewar about

5513

small problems because of misunderstandings. So if you have problems with your

5514

interlocutor, ask for help on the corresponding l10n mailing list, on

5515

debian-i18n, or even on debian-devel (but beware, l10n discussions very often

5516

become flamewars on that list :)

5517

<item>

5518

In any case, cooperation can only be achieved with mutual respect.

5519

</list>

5520

5521

5522

<appendix id="tools">Overview of Debian Maintainer Tools

5523

5524

This section contains a rough overview of the tools available to

5525

maintainers. The following is by no means complete or definitive, but

5526

just a guide to some of the more popular tools.

5527

5528

Debian maintainer tools are meant to aid developers and

5529

free their time for critical tasks. As Larry Wall says, there's more

5530

than one way to do it.

5531

5532

Some people prefer to use high-level package maintenance tools and

5533

some do not. Debian is officially agnostic on this issue; any tool

5534

which gets the job done is fine. Therefore, this section is not meant

5535

to stipulate to anyone which tools they should use or how they should

5536

go about their duties of maintainership. Nor is it meant to

5537

endorse any particular tool to the exclusion of a competing tool.

5538

5539

Most of the descriptions of these packages come from the actual

5540

package descriptions themselves. Further information can be found in

5541

the package documentation itself. You can also see more info with the

5542

command <tt>apt-cache show <package-name></tt>.

5543

5544

5545

<heading>Core tools</heading>

5546

5547

The following tools are pretty much required for any maintainer.

5548

5549

5550

5551

5552

<package>dpkg-dev</package> contains the tools (including

5553

<prgn>dpkg-source</prgn>) required to unpack, build, and upload Debian

5554

source packages. These utilities contain the fundamental, low-level

5555

functionality required to create and manipulate packages; as such,

5556

they are essential for any Debian maintainer.

5557

5558

5559

<heading><package>debconf</package></heading>

5560

5561

<package>debconf</package> provides a consistent interface to

5562

configuring packages interactively. It is user interface

5563

independent, allowing end-users to configure packages with a

5564

text-only interface, an HTML interface, or a dialog interface. New

5565

interfaces can be added as modules.

5566

5567

You can find documentation for this package in the

5568

<package>debconf-doc</package> package.

5569

5570

Many feel that this system should be used for all packages which require

5571

interactive configuration; see <ref id="bpp-config-mgmt">.

5572

<package>debconf</package> is not currently required by Debian Policy,

5573

but that may change in the future.

5574

</sect1>

5575

5576

5577

<heading><package>fakeroot</package>

5578

5579

<package>fakeroot</package> simulates root privileges. This enables

5580

you to build packages without being root (packages usually want to

5581

install files with root ownership). If you have

5582

<package>fakeroot</package> installed, you can build packages as a

5583

regular user: <tt>dpkg-buildpackage -rfakeroot</tt>.

5584

</sect1>

5585

</sect>

5586

5587

5588

<heading>Package lint tools</heading>

5589

5590

According to the Free On-line Dictionary of Computing (FOLDOC), `lint'

5591

is "a Unix C language processor which carries out more thorough checks

5592

on the code than is usual with C compilers." Package lint tools help

5593

package maintainers by automatically finding common problems and

5594

policy violations in their packages.

5595

5596

5597

<heading><package>lintian</package></heading>

5598

5599

<package>lintian</package> dissects Debian packages and emits

5600

information about bugs

5601

and policy violations. It contains automated checks for many aspects

5602

of Debian policy as well as some checks for common errors.

5603

5604

You should periodically get the newest <package>lintian</package> from

5605

`unstable' and check over all your packages. Notice that the <tt>-i</tt>

5606

option provides detailed explanations of what each error or warning means,

5607

what its basis in Policy is, and commonly how you can fix the problem.

5608

5609

Refer to <ref id="sanitycheck"> for more information on how and when

5610

to use Lintian.

5611

5612

You can also see a summary of all problems reported by Lintian on your

5613

packages at <url id="&url-lintian;">. These reports contain the latest

5614

<prgn>lintian</prgn> output for the whole development distribution

5615

("unstable").

5616

</sect1>

5617

5618

5619

<heading><package>linda</package></heading>

5620

5621

<package>linda</package> is another package linter. It is similar to

5622

<package>lintian</package> but has a different set of checks. Its

5623

written in Python rather than Perl.

5624

</sect1>

5625

5626

5627

<heading><package>debdiff</package></heading>

5628

5629

<prgn>debdiff</prgn> (from the <package>devscripts</package> package, <ref id="devscripts">)

5630

compares file lists and control files of two packages. It is a simple

5631

regression test, as it will help you notice if the number of binary

5632

packages has changed since the last upload, or if something has changed

5633

in the control file. Of course, some of the changes it reports will be

5634

all right, but it can help you prevent various accidents.

5635

5636

You can run it over a pair of binary packages:

5637

5638

debdiff package_1-1_arch.deb package_2-1_arch.deb

5639

</example>

5640

5641

Or even a pair of changes files:

5642

5643

debdiff package_1-1_arch.changes package_2-1_arch.changes

5644

</example>

5645

5646

For more information please see <manref name="debdiff" section="1">.

5647

</sect1>

5648

5649

</sect>

5650

5651

5652

5653

<heading>Helpers for <file>debian/rules</file></heading>

5654

5655

Package building tools make the process of writing

5656

<file>debian/rules</file> files easier. See <ref id="helper-scripts">

5657

for more information about why these might or might not be desired.

5658

5659

5660

<heading><package>debhelper</package></heading>

5661

5662

<package>debhelper</package> is a collection of programs which can be

5663

used in <file>debian/rules</file> to automate common tasks related to

5664

building binary Debian packages. <package>debhelper</package> includes

5665

programs to install

5666

various files into your package, compress files, fix file permissions,

5667

and integrate your package with the Debian menu system.

5668

5669

Unlike some approaches, <package>debhelper</package> is broken into

5670

several small, simple commands which act in a consistent manner. As

5671

such, it allows more fine-grained control than some of the

5672

other "debian/rules tools".

5673

5674

There are a number of little <package>debhelper</package> add-on

5675

packages, too transient to document. You can see the list of most of

5676

them by doing <tt>apt-cache search ^dh-</tt>.

5677

</sect1>

5678

5679

5680

<heading><package>debmake</package>

5681

5682

<package>debmake</package>, a precursor to

5683

<package>debhelper</package>, is a more coarse-grained

5684

<file>debian/rules</file> assistant. It includes two main programs:

5685

<prgn>deb-make</prgn>, which can be used to help a maintainer convert

5686

a regular (non-Debian) source archive into a Debian source package;

5687

and <prgn>debstd</prgn>, which incorporates in one big shot the same

5688

sort of automated functions that one finds in

5689

<package>debhelper</package>.

5690

5691

The consensus is that <package>debmake</package> is now deprecated in

5692

favor of <package>debhelper</package>. It is a bug to use

5693

<package>debmake</package> in new packages. New packages using

5694

<package>debmake</package> will be rejected from the archive.

5695

</sect1>

5696

5697

5698

5699

5700

The <package/dh-make/ package contains <prgn/dh_make/, a program that

5701

creates a skeleton of files necessary to build a Debian package out of

5702

a source tree. As the name suggests, <prgn/dh_make/ is a rewrite of

5703

<package/debmake/ and its template files use dh_* programs from

5704

<package/debhelper/.

5705

5706

While the rules files generated by <prgn/dh_make/ are in general a

5707

sufficient basis for a working package, they are still just the groundwork:

5708

the burden still lies on the maintainer to finely tune the generated files

5709

and make the package entirely functional and Policy-compliant.

5710

</sect1>

5711

5712

5713

5714

5715

<package>yada</package> is another packaging helper tool. It uses a

5716

<file>debian/packages</file> file to auto-generate

5717

<file>debian/rules</file> and other necessary files in the

5718

<file>debian/</file> subdirectory. The <file>debian/packages</file> file

5719

contains instruction to build packages and there is no need to create any

5720

<file>Makefile</file> files. There is possibility to

5721

use macro engine similar to the one used in SPECS files from RPM

5722

source packages.

5723

5724

For more informations see

5725

<tt><url id="http://yada.alioth.debian.org/" name="YADA site"></tt>.

5726

</sect1>

5727

5728

5729

<heading><package>equivs</package>

5730

5731

<package>equivs</package> is another package for making packages. It

5732

is often suggested for local use if you need to make a package simply

5733

to fulfill dependencies. It is also sometimes used when making

5734

``meta-packages'', which are packages whose only purpose is to depend

5735

on other packages.

5736

</sect1>

5737

</sect>

5738

5739

5740

5741

5742

<heading>Package builders</heading>

5743

5744

The following packages help with the package building process, general

5745

driving <prgn>dpkg-buildpackage</prgn> as well as handling supporting

5746

tasks.

5747

5748

5749

<heading><package>cvs-buildpackage</package>

5750

5751

<package>cvs-buildpackage</package> provides the capability to inject

5752

or import Debian source packages into a CVS repository, build a Debian

5753

package from the CVS repository, and helps in integrating upstream

5754

changes into the repository.

5755

5756

These utilities provide an infrastructure to facilitate the use of CVS

5757

by Debian maintainers. This allows one to keep separate CVS branches

5758

of a package for stable, unstable and possibly

5759

experimental distributions, along with the other benefits of

5760

a version control system.

5761

</sect1>

5762

5763

5764

<heading><package>debootstrap</package></heading>

5765

5766

The <package>debootstrap</package> package and script allows you to

5767

"bootstrap" a Debian base system into any part of your filesystem.

5768

By "base system", we mean the bare minimum of packages required to

5769

operate and install the rest of the system.

5770

5771

Having a system like this can be useful in many ways. For instance,

5772

you can <prgn>chroot</prgn> into it if you want to test your build

5773

dependencies. Or you can test how your package behaves when installed

5774

into a bare base system. Chroot builders use this package; see below.

5775

</sect1>

5776

5777

5778

<heading><package>pbuilder</package></heading>

5779

5780

<package>pbuilder</package> constructs a chrooted system, and builds a

5781

package inside the chroot. It is very useful to check that a package's

5782

build-dependencies are correct, and to be sure that unnecessary and

5783

wrong build dependencies will not exist in the resulting package.

5784

5785

A related package is <package>pbuilder-uml</package>, which goes even

5786

further by doing the build within a User Mode Linux environment.

5787

</sect1>

5788

5789

5790

<heading><package>sbuild</package></heading>

5791

5792

<package>sbuild</package> is another automated builder. It can use

5793

chrooted environments as well. It can be used stand-alone, or as part

5794

of a networked, distributed build environment. As the latter, it is

5795

part of the system used by porters to build binary packages for all

5796

the available architectures. See <ref id="buildd"> for more

5797

information, and <url id="&url-buildd;"> to see the system in

5798

action.

5799

</sect1>

5800

</sect>

5801

5802

5803

<heading>Package uploaders</heading>

5804

5805

The following packages help automate or simplify the process of

5806

uploading packages into the official archive.

5807

5808

5809

<heading><package>dupload</package></heading>

5810

5811

<package>dupload</package> is a package and a script to automatically

5812

upload Debian packages to the Debian archive, to log the upload, and

5813

to send mail about the upload of a package. You can configure it for

5814

new upload locations or methods.

5815

</sect1>

5816

5817

5818

5819

5820

The <package>dput</package> package and script does much the same

5821

thing as <package>dupload</package>, but in a different way. It has

5822

some features over <package>dupload</package>, such as the ability to

5823

check the GnuPG signature and checksums before uploading, and the

5824

possibility of running <prgn>dinstall</prgn> in dry-run mode after the

5825

upload.

5826

</sect1>

5827

5828

5829

5830

The <package>dcut</package> script (part of the package <ref id="dput">)

5831

helps in removing files from the ftp upload directory.

5832

</sect1>

5833

</sect>

5834

5835

5836

<heading>Maintenance automation</heading>

5837

5838

The following tools help automate different maintenance tasks, from

5839

adding changelog entries or signature lines and looking up bugs in Emacs

5840

to making use of the newest and official

5841

<file>config.sub</file>.

5842

5843

5844

<heading><package>devscripts</package></heading>

5845

5846

<package>devscripts</package> is a package containing wrappers

5847

and tools which are very helpful for maintaining your Debian

5848

packages. Example scripts include <prgn>debchange</prgn> and

5849

<prgn>dch</prgn>, which manipulate your <file>debian/changelog</file>

5850

file from the command-line, and <prgn>debuild</prgn>, which is a

5851

wrapper around <prgn>dpkg-buildpackage</prgn>. The <prgn>bts</prgn>

5852

utility is also very helpful to update the state of bug reports on the

5853

command line. <prgn>uscan</prgn> can be used to watch for new upstream

5854

versions of your packages. <prgn>debrsign</prgn> can be used to

5855

remotely sign a package prior to upload, which is nice when the

5856

machine you build the package on is different from where your GPG keys

5857

are.

5858

5859

See the <manref name="devscripts" section="1"> manual page for a

5860

complete list of available scripts.

5861

</sect1>

5862

5863

5864

<heading><package>autotools-dev</package></heading>

5865

5866

<package>autotools-dev</package>

5867

contains best practices for people who maintain packages which use

5868

<prgn>autoconf</prgn> and/or <prgn>automake</prgn>. Also contains

5869

canonical <file>config.sub</file> and <file>config.guess</file> files

5870

which are known to work on all Debian ports.

5871

</sect1>

5872

5873

5874

<heading><package>dpkg-repack</package></heading>

5875

5876

<prgn>dpkg-repack</prgn> creates Debian package file out of a package

5877

that has already been installed. If any changes have been made to the

5878

package while it was unpacked (e.g., files in <file>/etc</file> were

5879

modified), the new package will inherit the changes.

5880

5881

This utility can make it easy to copy packages from one computer to

5882

another, or to recreate packages which are installed on your system

5883

but no longer available elsewhere, or to save the current state of a

5884

package before you upgrade it.

5885

</sect1>

5886

5887

5888

<heading><package>alien</package></heading>

5889

5890

<prgn>alien</prgn> converts binary packages between various packaging

5891

formats, including Debian, RPM (RedHat), LSB (Linux Standard Base),

5892

Solaris, and Slackware packages.

5893

</sect1>

5894

5895

5896

<heading><package>debsums</package></heading>

5897

5898

<prgn>debsums</prgn> checks installed packages against their MD5 sums.

5899

Note that not all packages have MD5 sums, since they aren't required

5900

by Policy.

5901

</sect1>

5902

5903

5904

5905

5906

<package>dpkg-dev-el</package> is an Emacs lisp package which provides

5907

assistance when editing some of the files in the <file>debian</file>

5908

directory of your package. For instance,

5909

there are handy functions for

5910

listing a package's current bugs,

5911

and for finalizing the latest entry in a

5912

<file>debian/changelog</file> file.

5913

</sect1>

5914

5915

5916

<heading><package>dpkg-depcheck</package></heading>

5917

5918

<prgn>dpkg-depcheck</prgn> (from the <package>devscripts</package>

5919

package, <ref id="devscripts">)

5920

runs a command under <prgn>strace</prgn> to determine all the packages that

5921

were used by the said command.

5922

5923

For Debian packages, this is useful when you have to compose a

5924

<tt>Build-Depends</tt> line for your new package: running the build

5925

process through <prgn>dpkg-depcheck</prgn> will provide you with a

5926

good first approximation of the build-dependencies. For example:

5927

5928

dpkg-depcheck -b debian/rules build

5929

</example>

5930

5931

<prgn>dpkg-depcheck</prgn> can also be used to check for run-time

5932

dependencies, especially if your package uses exec(2) to run other

5933

programs.

5934

5935

For more information please see <manref name="dpkg-depcheck" section="1">.

5936

</sect1>

5937

5938

</sect>

5939

5940

5941

5942

<heading>Porting tools</heading>

5943

5944

The following tools are helpful for porters and for

5945

cross-compilation.

5946

5947

5948

<heading><package>quinn-diff</package>

5949

5950

<package>quinn-diff</package> is used to locate the differences from

5951

one architecture to another. For instance, it could tell you which

5952

packages need to be ported for architecture <var>Y</var>, based on

5953

architecture <var>X</var>.

5954

5955

5956

<heading><package>dpkg-cross</package>

5957

5958

<package>dpkg-cross</package> is a tool for installing libraries and

5959

headers for cross-compiling in a way similar to

5960

<package>dpkg</package>. Furthermore, the functionality of

5961

<prgn>dpkg-buildpackage</prgn> and <prgn>dpkg-shlibdeps</prgn> is

5962

enhanced to support cross-compiling.

5963

</sect1>

5964

5965

5966

5967

<heading>Documentation and information</heading>

5968

5969

The following packages provide information for maintainers or help

5970

with building documentation.

5971

5972

5973

<heading><package>debiandoc-sgml</package></heading>

5974

5975

<package>debiandoc-sgml</package> provides the DebianDoc SGML DTD,

5976

which is commonly used for Debian documentation. This manual, for

5977

instance, is written in DebianDoc. It also provides scripts for

5978

building and styling the source to various output formats.

5979

5980

Documentation for the DTD can be found in the

5981

<package>debiandoc-sgml-doc</package> package.

5982

</sect1>

5983

5984

5985

<heading><package>debian-keyring</package></heading>

5986

5987

Contains the public GPG and PGP keys of Debian developers. See <ref

5988

id="key-maint"> and the package documentation for more

5989

information.

5990

</sect1>

5991

5992

5993

<heading><package>debview</package></heading>

5994

5995

<package>debview</package> provides an Emacs mode for viewing Debian

5996

binary packages. This lets you examine a package without unpacking

5997

it.

5998

</sect1>

5999

</sect>

6000

6001

<!-- FIXME: add the following

6002

6003

questionable:

6004

dbs (referred to above)

6005

dpatch (referred to above)

6006

debarchiver

6007

ucf

6008

dpkg-awk

6009

grep-dctrl

6010

d-shlibs

6011

wajig

6012

magpie

6013

apt-dpkg-ref

6014

apt-show-source

6015

apt-show-versions

6016

pdbv

6017

epm

6018

apt-src

6019

apt-build

6020

6021

rejected:

6022

debaux: too new, unmaintained?

6023

dh-make-perl: too new, unmaintained?

6024

-->

6025

6026

</appendix>

6027

</book>

6028

</debiandoc>

6029

6030

<!-- Keep this comment at the end of the file

6031

Local variables:

6032

mode: sgml

6033

sgml-omittag:t

6034

sgml-shorttag:t

6035

sgml-minimize-attributes:nil

6036

sgml-always-quote-attributes:t

6037

sgml-indent-step:2

6038

sgml-indent-data:nil

6039

sgml-parent-document:nil

6040

sgml-exposed-tags:nil

6041

sgml-declaration:nil

6042

sgml-local-catalogs:nil

6043

sgml-local-ecat-files:nil

6044

End:

6045

-->