# 6. Buone pratiche per la pacchettizzazione

Debian's quality is largely due to the Debian Policy, which defines explicit baseline requirements that all Debian packages must fulfill. Yet there is also a shared history of experience which goes beyond the Debian Policy, an accumulation of years of experience in packaging. Many very talented people have created great tools, tools which help you, the Debian maintainer, create and maintain excellent packages.

Questo capitolo fornisce alcune buone pratiche per gli sviluppatori Debian. Tutte le raccomandazioni sono solo tali, e non sono requisiti o policy. Questi sono solo alcuni spunti soggettivi, i consigli e i punti raccolti da sviluppatori Debian. Ci si senta liberi di scegliere quello che funziona meglio.

## 6.1. Buone pratiche per `debian/rules`

The following recommendations apply to the `debian/rules` file. Since `debian/rules` controls the build process and selects the files that go into the package (directly or indirectly), it's usually the file maintainers spend the most time on.

### 6.1.1. Script di supporto

L'idea nell'utilizzo degli script di aiuto in `debian/rules` è che essi hanno consentito ai maintainer di usare e condividere la logica comune tra molti pacchetti. Si prenda per esempio la questione dell'installazione delle voci di menu: è necessario mettere il file in `/usr/share/menu` (o `/usr/lib/menu` per gli eseguibili binari dei menufile, se questo è necessario), e aggiungere i comandi agli script del maintainer per registrare ed annullare la registrazione delle voci di menu. Dal momento che questa è una cosa molto comune da fare con i pacchetti, perché ogni maintainer dovrebbe riscrivere tutto questo da solo, a volte con bug? Inoltre, supponendo che la cartella menu cambi, ogni pacchetto dovrebbe essere cambiato.

Gli script di supporto si occupano di questi problemi. Supponendo che ci si attenga alle convenzioni previste dallo script di supporto, quest'ultimo si prende cura di tutti i dettagli. Cambiamenti nella policy possono essere effettuati nello script helper; successivamente i pacchetti avranno solo bisogno di essere ricompilati con la nuova versione dell'helper e nessuna ulteriore modifica.

Panoramica degli strumenti del Debian Maintainer contiene un paio di diversi script di supporto. Il sistema di supporto più comune e migliore (a nostro parere) è `debhelper`. I sistemi di supporto precedenti, come `debmake`, erano monolitici: non si poteva scegliere quale parte dell'helper si riteneva utile, ma si doveva usare l'helper per fare tutto. `debhelper`, invece, è una serie di programmi piccoli e separati `dh_*`. Per esempio, `dh_installman` installa e comprime le pagine man, `dh_installmenu` installa i file di menu, e così via. Così, si offre sufficiente flessibilità per essere in grado di utilizzare i piccoli script di aiuto, dove utile, in abbinamento con i comandi manuali in `debian/rules`.

You can get started with `debhelper` by reading debhelper(7) and looking at the examples that come with the package. `dh_make`, from the `dh-make` package (see dh-make), can be used to convert a vanilla source package to a `debhelper`ized package. This shortcut, though, should not convince you that you do not need to bother understanding the individual `dh_*` helpers. If you are going to use a helper, you do need to take the time to learn to use that helper, to learn its expectations and behavior.

### 6.1.2. Pacchetti binari multipli

A single source package will often build several binary packages, either to provide several flavors of the same software (e.g., the `vim` source package) or to make several small packages instead of a big one (e.g., so the user can install only the subset needed, and thus save some disk space, see for example the `libxml2` source package).

Il secondo caso può essere facilmente gestito in `debian/rules`. Bisogna solo spostare i file appropriati dalla cartella di compilazione in alberi temporanei del pacchetto. È possibile farlo utilizzando `install` o `dh_install` da `debhelper`. Ci si assicuri di controllare le diverse permutazioni dei vari pacchetti, assicurandosi di avere il corretto insieme di dipendenze tra pacchetti in `debian/control`.

The first case is a bit more difficult since it involves multiple recompiles of the same software but with different configuration options. The `vim` source package is an example of how to manage this using a hand-crafted `debian/rules` file.

## 6.2. Buone pratiche per `debian/control`

Le seguenti pratiche sono rilevanti per il file`debian/control`. Esse integrano la Policy sulla descrizione dei pacchetti.

La descrizione del pacchetto, come definito dal corrispondente campo nel file `control`, contiene sia la sinossi del pacchetto sia la descrizione lunga del pacchetto. Linee guida generali per le descrizioni dei pacchetti descrive le linee guida comuni ad entrambe le parti della descrizione del pacchetto. In seguito, La sinossi del pacchetto, o una breve descrizione fornisce specifiche linee guida per la sinossi e La descrizione lunga contiene specifiche linee guida per la descrizione.

### 6.2.1. The package name

The package name:

- Must be consistent with widely established conventions, e.g.

  - C and C++ libraries are typically prefixed with lib

  - for many other languages, package names are prefixed or a suffixed with the language name (the actual convention depends on the language).

- Should not be a common, unqualified word. In particular, words that represent a whole class of applications (e.g. reader, browser) should be reserved for virtual packages.

- Should ideally be at least 4 characters long, unless the upstream name is shorter than that and the project is already widely recognized by that name (e.g. fzf).

### 6.2.2. Linee guida generali per le descrizioni dei pacchetti

La descrizione del pacchetto dovrebbe essere scritta probabilmente per l'utente medio, la persona media che utilizzerà ed avrà benefici dal pacchetto. Per esempio, pacchetti di sviluppo sono per gli sviluppatori e possono essere di natura tecnica nella loro linguaggio. Applicazioni più generiche, come gli editor, dovrebbero essere scritte per un utente meno tecnico.

La nostra analisi delle descrizioni dei pacchetti ci porta a concludere che la maggior parte delle descrizioni dei pacchetti sono di natura tecnica, cosi è, non sono scritte per avere senso per gli utenti non tecnici. A meno che il proprio pacchetto non sia realmente solo per utenti tecnici, questo costituisce un problema.

Come si scrive per gli utenti non tecnici? Si eviti il gergo. Evitare di riferirsi ad altre applicazioni o framework che l'utente potrebbe non conoscere - GNOME o KDE va bene, dal momento che gli utenti hanno probabilmente familiarità con questi termini, ma GTK probabilmente non lo è. Cercare di ipotizzare nessuna conoscenza a priori. Se è necessario utilizzare termini tecnici, spiegarli.

Si sia obiettivi. Le descrizioni dei pacchetti non sono il posto per promuovere il proprio pacchetto, non importa quanto lo si ami. Ricordare che il lettore potrebbe non essere interessato alle stesse cose che vi interessano.

I riferimenti ai nomi di eventuali altri pacchetti software, nomi di protocollo, standard o specifiche dovrebbero utilizzare la forma canonica, se ne esiste una. Ad esempio, utilizzare X Window System, X11 o X, non X Windows, X-Windows o X Window. Utilizzare GTK, non GTK+ o gtk. Usare GNOME, non Gnome. Utilizzare PostScript, non Postscript o postscript.

Se si hanno problemi di scrittura della descrizione, si potrebbe desiderare di inviarla all'indirizzo di posta elettronica `debian-l10n-english@lists.debian.org` richiedendo un parere.

### 6.2.3. La sinossi del pacchetto, o una breve descrizione

La policy dice che la linea di sinossi (la breve descrizione) deve essere concisa ma anche informativa, non ripetendo il nome del pacchetto.

Le sinossi funziona come una frase che descrive il pacchetto, non una frase completa, perciò la punteggiatura è inappropriata: non ha bisogno di lettere maiuscole in più o un punto finale (punto). Dovrebbe anche omettere qualsiasi iniziale articolo indefinito o definito - «a», «un» o «il». Così, per esempio:

    Package: libeg0
    Description: exemplification support library

Tecnicamente si tratta di un sintagma nominale senza articoli, al contrario di una frase verbale. Una buona euristica è che dovrebbe essere possibile sostituire il nome e la sinossi del pacchetto in questa formula:

Il pacchetto name fornisce {a, un, il, alcuni} sinossi.

Insiemi di pacchetti correlati possono utilizzare uno schema alternativo che divide la sinossi in due parti, la prima una descrizione di tutta la suite e la seconda una sintesi del ruolo del pacchetto all'interno di essa:

    Package: eg-tools
    Description: simple exemplification system (utilities)

    Package: eg-doc
    Description: simple exemplification system - documentation

Queste sinossi seguono una formula modificata. Quando un pacchetto «name» ha una «suite di sinossi (role) » o «suite - role», gli elementi devono essere formulati in modo che si inseriscano nella formula:

Il name del pacchetto fornisce {a, un, il} role per la suite.

### 6.2.4. La descrizione lunga

La descrizione lunga è la principale informazione sul pacchetto disponibile agli utenti prima che lo si installi. Essa dovrebbe fornire tutte le informazioni necessarie per permettere all'utente di decidere se installare il pacchetto. Si supponga che l'utente abbia già letto la sinossi del pacchetto.

La descrizione lunga deve essere composta da frasi complete ed esaustive.

Il primo paragrafo della descrizione lunga deve rispondere alle seguenti domande: che cosa fa il pacchetto? in che modo aiuta l'utente ad assolvere ai suoi task? È importante descrivere ciò in maniera non tecnica, salvo ovviamente quando il pacchetto è destinato ad una utenza tecnica.

Long descriptions of related packages, for example built from the same source, can share paragraphs in order to increase consistency and reduce the workload for translators, but you need at least one separate paragraph describing the package's specific role.

The following paragraphs should answer the following questions: Why do I as a user need this package? What other features does the package have? What outstanding features and deficiencies are there compared to other packages (e.g., if you need X, use Y instead)? Is this package related to other packages in some way that is not handled by the package manager (e.g., is this the client for the foo server)?

Fare attenzione ad evitare errori di ortografia e di grammatica. Ci si assicuri di effettuare il controllo ortografico. Entrambi `ispell` e `aspell` hanno modalità speciali per il controllo del file `debian/control`:

    ispell -d american -g debian/control

    aspell -d en -D -c debian/control

Gli utenti di solito si aspettano che queste domande ricevano risposta nella descrizione del pacchetto:

- Che cosa fa il pacchetto? Se si tratta di un componente aggiuntivo per un altro pacchetto, allora la breve descrizione del pacchetto per il quale è un componente aggiuntivo dovrebbe essere inserita qui.

- Perché dovrei volere questo pacchetto? Questo è legato al precedente, ma non è lo stesso (questo è un client di posta elettronica; questo è eccezionale, veloce, si interfaccia con PGP e LDAP e IMAP, ha caratteristiche X, Y e Z).

- Se il pacchetto non deve essere installato direttamente, ma è richiamato da un altro pacchetto, questo dovrebbe essere menzionato.

- Se il pacchetto è `experimental`, o ci sono altri motivi per i quali non dovrebbe essere usato, se invece ci sono altri pacchetti che dovrebbero essere utilizzati, esso dovrebbe essere indicato.

- How is this package different from the competition? Is it a better implementation? more features? different features? Why should I choose this package?

### 6.2.5. Home page originale del pacchetto

Si consiglia di aggiungere l'URL per la home page del pacchetto nel campo `Homepage` della sezione `Source` in `debian/control`. L'aggiunta di questa informazione nella descrizione del stesso pacchetto è considerata obsoleta.

### 6.2.6. La posizione del Version Control System

Ci sono campi aggiuntivi per la posizione del Version Control System in `debian/control`.

#### 6.2.6.1. Vcs-Browser

Value of this field should be a `https://` URL pointing to a web-browsable copy of the Version Control System repository used to maintain the given package, if available.

L'informazione è destinata ad essere utile per l'utente finale, disposto a sfogliare l'ultimo lavoro svolto sul pacchetto (ad esempio quando si cerca la patch di un bug etichettato come `pending` nel sistema di bug tracking).

#### 6.2.6.2. Vcs-*

Value of this field should be a string identifying unequivocally the location of the Version Control System repository used to maintain the given package, if available. `*` identifies the Version Control System; currently the following systems are supported by the package tracking system: `arch`, `bzr` (Bazaar), `cvs`, `darcs`, `git`, `hg` (Mercurial), `mtn` (Monotone), `svn` (Subversion).

L'informazione è destinata ad essere utile per un utente esperto nel dato Version Control System e disposto a compilare la versione attuale del pacchetto dai sorgenti VCS. Altri usi di queste informazioni possono includere compilazioni automatiche della versione VCS più recente del dato pacchetto. A tal fine la posizione a cui punta il campo dovrebbe essere la versione migliore rispetto a quella agnostica e puntare al ramo principale (per i VCS che supportano tale concetto). Inoltre, la posizione indicata dovrebbe essere accessibile per l'utente finale; soddisfare questo requisito potrebbe implicare un accesso anonimo al repository invece di puntare a una versione SSH-accessibile dello stesso.

In the following example, an instance of the field for a Git repository of the `vim` package is shown. Note how the URL is in the `https://` scheme (instead of `ssh://`). The use of the `Vcs-Browser` and `Homepage` fields described above is also shown.

    Source: vim
    <snip>
    Vcs-Git: https://salsa.debian.org/vim-team/vim.git
    Vcs-Browser: https://salsa.debian.org/vim-team/vim
    Homepage: https://www.vim.org

Maintaining the packaging in a version control system, and setting a Vcs-* header is good practice and makes it easier for others to contribute changes.

Almost all packages in Debian that use a version control system use Git; if you create a new package, using Git is a good idea simply because it's the system that contributors will be familiar with.

DEP-14 defines a common layout for Debian packages.

## 6.3. Buone pratiche per il `debian/changelog`

Le seguenti pratiche integrano la Policy sui file changelog.

### 6.3.1. Scrivere informazioni utili nel file changelog

La voce del changelog inerente una revisione del pacchetto documenta i cambiamenti in quella specifica revisione e solo loro. Concentrarsi sulla descrizione di cambiamenti significativi e visibili all'utente che sono stati fatti dopo l'ultima versione.

Ci si concentri su ciò che è stato cambiato: chi, come e quando di solito sono meno importanti. Detto questo, ricordarsi di citare le persone che hanno fornito un notevole aiuto nel compilare il pacchetto (ad esempio, coloro che hanno inviato delle patch).

Non c'è bisogno di elaborare le modifiche banali e ovvie. È inoltre possibile aggregare diversi cambiamenti in un'unica voce. D'altra parte, non si sia troppo ermetici se si ha intrapreso un cambiamento importante. Si sia particolarmente chiari se ci sono cambiamenti che influenzano il comportamento del programma. Per ulteriori chiarimenti, utilizzare il `README.Debian`.

Si utilizzi l'inglese comune in modo che la maggior parte dei lettori possa comprenderlo. Si evitino abbreviazioni, termini tecnici e gergo quando si spiegano i cambiamenti che chiudono i bug, soprattutto per i bug segnalati dagli utenti che non sembrano particolarmente smaliziati dal punto di vista tecnico. Si sia gentili, non si imprechi.

A volte è desiderabile far precedere le voci del changelog con i nomi dei file che sono stati modificati. Tuttavia, non c'è bisogno di elencare esplicitamente uno per uno tutti i file modificati, soprattutto se il cambiamento è stato piccolo o ripetitivo. È possibile utilizzare i metacaratteri.

Quando si parla di bug, non si dia per scontato nulla. Dire quale era il problema, come è stato risolto e aggiungere in fondo la stringa closes: #nnnnn. Per ulteriori informazioni, si consulti Quando i bug vengono chiusi da nuovi upload.

### 6.3.2. Selecting the upload urgency

The release team have indicated that they expect most uploads to `unstable` to use urgency=medium. That is, you should choose urgency=medium unless there is some particular reason for the upload to migrate to `testing` more quickly or slowly (see also Aggiornamenti da unstable). For example, you might select urgency=low if the changes since the last upload are large and might be disruptive in unanticipated ways.

The delays are currently 2, 5 or 10 days, depending on the urgency (high, medium or low). The actual numbers are actually controled by the britney configuration which also includes accelerated migrations when Autopkgtest passes.

### 6.3.3. Comuni incomprensioni sulle voci del changelog

Le voci del changelog non dovrebbero documentare generici problemi di packaging (Ehi, se si è alla ricerca di foo.conf, è in /etc/blah/.), dal momento che si suppone che gli amministratori e gli utenti siano a conoscenza di come queste cose sono generalmente gestite sui sistemi Debian. Parlatene, tuttavia, se si modifica la posizione di un file di configurazione.

Gli unici bug chiusi con una voce nel changelog dovrebbero essere quelli che sono effettivamente chiusi nella stessa versione del pacchetto. Chiudere bug non correlati nel changelog è cattiva pratica. Si veda Quando i bug vengono chiusi da nuovi upload.

Le voci del changelog non dovrebbero essere utilizzate per discussioni casuali con chi ha segnalato il bug (non vedo segmentation fault quando avvio foo con l'opzione bar; invia più informazioni al riguardo), dichiarazioni generali sulla vita, l'universo e tutto il resto (scusate questo caricamento mi ha preso così tanto tempo, ma ho preso l'influenza), o richieste di aiuto (la lista di bug su questo pacchetto è enorme, vi prego di dare una mano). Queste cose di solito non vengono notate, ma possono infastidire le persone che desiderano leggere le informazioni sulle modifiche effettive nel pacchetto. Per ulteriori informazioni su come utilizzare il sistema di bug tracking vedere Rispondere ai bug.

Si tratta di una vecchia tradizione per riconoscere bug corretti in un caricamento di un non-maintainer nella prima voce del changelog dell'appropriato maintainer. Siccome ora abbiamo il version tracking, è sufficiente mantenere le voci del changelog NMUed e citare questo fatto nella propria voce del changelog.

### 6.3.4. Errori frequenti nelle voci del changelog

I seguenti esempi dimostrano alcuni errori comuni o di cattivo stile nelle voci del changelog.

    * Fixed all outstanding bugs.

Questo non dice ai lettori qualcosa di particolarmente utile, ovviamente.

    * Applied patch from Jane Random.

Qual'era l'argomento della patch?

    * Late night install target overhaul.

Revisione che ha completato cosa? L'ipotetica citazione notturna è lì a ricordarci che non dovremmo fidarci di quel codice?

    * Fix vsync fw glitch w/ ancient CRTs.

Too many acronyms (what does "fw" mean, "firmware"?), and it's not overly clear what the glitch was actually about, or how it was fixed.

    * This is not a bug, closes: #nnnnnn.

Innanzitutto, non c'è assolutamente alcun bisogno di caricare il pacchetto per trasmettere queste informazioni; invece, utilizzare il sistema di bug tracking. In secondo luogo, non c'è alcuna spiegazione del perché il rapporto non è un bug.

    * Has been fixed for ages, but I forgot to close; closes: #54321.

If for some reason you didn't mention the bug number in a previous changelog entry, there's no problem, just close the bug normally in the BTS. There's no need to touch the changelog file, presuming the description of the fix is already in (this applies to the fixes by the upstream authors/maintainers as well; you don't have to track bugs that they fixed ages ago in your changelog).

    * Closes: #12345, #12346, #15432

Dov'è la descrizione? Se non è possibile pensare ad un messaggio descrittivo, iniziare inserendo il titolo di ogni differente bug.

### 6.3.5. Integrare i changelog con i file `NEWS.Debian`

Importanti novità sui i cambiamenti in un pacchetto possono anche essere inserite nei file `NEWS.Debian`. Le notizie saranno visualizzate da strumenti come `apt-listchanges`, prima di tutto il resto dei changelog. Questo è il mezzo preferito per permettere all'utente di conoscere i cambiamenti significativi in ??un pacchetto. È meglio che usare le note di `debconf` in quanto è meno fastidioso e l'utente può tornare indietro e vedere il file `NEWS.Debian` dopo l'installazione. Ed è meglio rispetto all'elencare i principali cambiamenti presenti in `README.Debian`, dal momento che l'utente può facilmente perderli.

Il formato del file è lo stesso di un file changelog Debian, ma lasciare fuori gli asterischi e descrivere ogni notizia con un paragrafo completo quando necessario, piuttosto che le più concise sintesi che andrebbero in un changelog. È una buona idea eseguire il file attraverso `dpkg-parsechangelog` per controllare la formattazione in quanto durante la fase di compilazione non sarà controllata automaticamente come è stato fatto per il changelog. Ecco un esempio di un vero e proprio file `NEWS.Debian`:

    cron (3.0pl1-74) unstable; urgency=low

        The checksecurity script is no longer included with the cron package:
        it now has its own package, checksecurity. If you liked the
        functionality provided with that script, please install the new
        package.

     -- Steve Greenland <stevegr@debian.org>  Sat,  6 Sep 2003 17:15:03 -0500

Il file `NEWS.Debian` è installato come `/usr/share/doc/`package`/NEWS.Debian.gz`. È compresso e ha sempre quel nome, anche in pacchetti nativi Debian. Se si utilizza `debhelper`, `dh_installchangelogs` installerà il file `debian/NEWS` per voi.

A differenza dei file changelog, non è necessario aggiornare il file `NEWS.Debian` ad ogni rilascio. Aggiornarli solo se si ha qualcosa particolarmente degna di nota che l'utente dovrebbe conoscere. Se non si ha alcuna notizia, non c'è bisogno di fornire un file `NEWS.Debian`. Nessuna notizia è una buona notizia!

## 6.4. Best practices around security

When an upstream publishes a cryptographic signature for every new release, you should setup `uscan` to automatically verify the latter. For details, refer to the section on `Upstream source location: "debian/watch"` in the The Debian Policy Manual.

https://wiki.debian.org/Hardening has suggestions on how to build security hardened executables.

## 6.5. Buone pratiche per gli script del mantainer

Maintainer scripts include the files `debian/postinst`, `debian/preinst`, `debian/prerm` and `debian/postrm`. These scripts take care of any package installation or deinstallation setup that isn't handled merely by the creation or removal of files and directories. The following instructions supplement the Debian Policy.

Gli script del maintainer devono essere idempotenti. Ciò significa che è necessario assicurarsi che nulla di male accadrà se lo script dovesse essere invocato due volte dove di solito viene lanciato una volta sola.

Gli standard input e output possono essere reindirizzati (ad esempio nelle pipe) per finalità di logging, quindi non utilizzateli come una tty.

Tutte le configurazioni suggerite o interattive devono essere ridotte al minimo. Quando è necessario, si dovrebbe utilizzare il pacchetto `debconf` per l'interfaccia. Ricordare che il suggerimento in ogni caso può esserci solo nella fase `configure` dello script `postinst`.

Mantenere gli script del maintainer più semplici possibile. Si consiglia di utilizzare puri script POSIX. Ricordate, se si ha bisogno di tutte le funzioni di bash, lo script del maintainer deve avere una linea shebang per bash. La shell POSIX o Bash sono preferite a quella Perl, poiché permettono a `debhelper` di aggiungere facilmente bit agli script.

Se si modificano gli script del maintainer, assicurarsi di testare la rimozione del pacchetto, la doppia installazione e l'epurazione. Assicurarsi che un pacchetto epurato sia completamente sparito, ovvero, deve rimuovere tutti i file creati, direttamente o indirettamente, in tutti gli script del maintainer.

Se è necessario verificare l'esistenza di un comando, si dovrebbe usare qualcosa simile a

    if command -v install-docs > /dev/null; then ...

You can use this function to search `$PATH` for a command name, passed as an argument. It returns true (zero) if the command was found, and false if not. This is really the best way, since `command -v` is a shell-builtin for many shells and is defined in POSIX.

Using `which` is an acceptable alternative, since it is from the required `debianutils` package.

## 6.6. Gestione della configurazione con `debconf`

`Debconf` is a configuration management system that can be used by all the various packaging scripts (`postinst` mainly) to request feedback from the user concerning how to configure the package. Direct user interactions must now be avoided in favor of `debconf` interaction. This will enable non-interactive installations in the future.

Debconf is a great tool but it is often poorly used. Many common mistakes are listed in the debconf-devel(7) man page. It is something that you must read if you decide to use debconf. Also, we document some best practices here.

Queste linee guida comprendono un certo stile di scrittura e di raccomandazioni tipografiche, considerazioni generali sull'uso di debconf e raccomandazioni più specifiche per alcune parti della distribuzione (il sistema di installazione, per esempio).

### 6.6.1. Non abusare di debconf

Da quando debconf è apparso in Debian, è stato ampiamente abusato e diverse critiche ricevute dalla distribuzione Debian provengono dall'abuso di debconf con la necessità di rispondere ad una vasta serie di domande prima di installare ogni piccola cosa.

Keep usage notes to where they belong: the `NEWS.Debian`, or `README.Debian` file. Only use notes for important notes that may directly affect the package usability. Remember that notes will always block the install until confirmed or bother the user by email.

Carefully choose the questions' priorities in maintainer scripts. See debconf-devel 7 for details about priorities. Most questions should use medium and low priorities.

### 6.6.2. Raccomandazioni generali per autori e traduttori

#### 6.6.2.1. Scrivere inglese corretto

La maggior parte dei maintainer dei pacchetti Debian non sono di madrelingua inglese. Quindi, la scrittura di modelli correttamente formulati, può non essere facile per loro.

utilizzare (e abusare) della mailing list `debian-l10n-english@lists.debian.org`. Avrete le vostre bozze di modelli corrette.

I modelli scritti male danno una cattiva immagine del pacchetto, del proprio lavoro... o anche di Debian stesso.

Evitare il gergo tecnico il più possibile. Se alcuni termini suonano comuni a voi, possono essere impossibili da comprendere per gli altri. Se non si possono evitare, cercare di spiegarli (utilizzare la descrizione estesa). Nel fare ciò, cercare di bilanciarsi tra verbosità e semplicità.

#### 6.6.2.2. Sii gentile con i traduttori

Debconf templates may be translated. Debconf, along with its sister package `po-debconf`, offers a simple framework for getting templates translated by translation teams or even individuals.

Utilizzare i modelli basati su gettext. Installare `po-debconf` sul proprio sistema di sviluppo e leggete la sua documentazione (`man po-debconf` è un buon inizio).

Avoid changing templates too often. Changing template text induces more work for translators, which will get their translation fuzzied. A fuzzy translation is a string for which the original changed since it was translated, therefore requiring some update by a translator to be usable. When changes are small enough, the original translation is kept in PO files but marked as `fuzzy`.

Se si ha intenzione di modificare i modelli originali, utilizzare il sistema di notifica fornito con il pacchetto `po-debconf`, vale a dire il `podebconf-report-po`, per contattare i traduttori. I Traduttori più attivi sono molto reattivi e ottenere il loro lavoro incluso insieme con i vostri modelli modificati vi risparmierà caricamenti aggiuntivi. Se si utilizzano modelli basati su gettext, il nome del traduttore e gli indirizzi di posta elettronica sono menzionati negli header dei file PO e saranno utilizzati da `podebconf-report-po`.

Un uso consigliato di ciò che questa utility è:

    cd debian/po && podebconf-report-po --call --languageteam --withtranslators --deadline="+10 days"

This command will first synchronize the PO and POT files in `debian/po` with the template files listed in `debian/po/POTFILES.in`. Then, it will send a call for new translations, in the `debian-i18n@lists.debian.org` mailing list. Finally, it will also send a call for translation updates to the language team (mentioned in the `Language-Team` field of each PO file) as well as the last translator (mentioned in `Last-translator`).

Dare una scadenza ai traduttori è sempre apprezzato, in modo tale che possano organizzare il loro lavoro. Ricordare che alcuni gruppi di traduzione hanno un processo formalizzato di traduzione/revisione e un ritardo inferiore a 10 giorni è considerato irragionevole. Un ritardo più breve mette troppa pressione sul team di traduzione e dovrebbe essere utilizzato per modifiche di minore entità.

In caso di dubbio, si può anche contattare il team di traduzione per una determinata lingua (debian-l10n-xxxxx@lists.debian.org), o la mailing list `debian-i18n@lists.debian.org`.

#### 6.6.2.3. Ordinare intere traduzioni quando si correggono errori di battitura e di ortografia

Quando il testo di un modello debconf è corretto e si è sicuri che la modifica non influenzi le traduzioni, si sia gentili con i traduttori e sistemare le loro traduzioni.

Se non si fa così, l'intero modello non verrà tradotto fino a quando un traduttore invierà un aggiornamento.

Per sistemare le traduzioni, è possibile utilizzare `msguntypot` (parte del pacchetto `po4a`).

1. Rigenerare i file POT e PO.

       debconf-updatepo

2. Creare una copia del file POT.

       cp templates.pot templates.pot.orig

3. Fare una copia di tutti i files PO.

       mkdir po_fridge; cp *.po po_fridge

4. Modificare i file dei modelli di debconf per correggere errori di battitura.

5. Rigenerare i file POT e PO (di nuovo).

       debconf-updatepo

   A questo punto, la correzione dell'errore di battitura ha confuso tutte le traduzioni e questo spiacevole cambiamento è l'unico tra i file PO della vostra cartella principale e quella in frigo. Ecco come risolvere questa situazione.

6. Scartare la traduzione disordinata, ripristinare quella proveniente dal frigo.

       cp po_fridge/*.po .

7. Unire manualmente i files PO con il nuovo file POT, ma prendendo nell'account l'inutile disordine.

       msguntypot -o templates.pot.orig -n templates.pot *.po

8. Pulizia.

       rm -rf templates.pot.orig po_fridge

#### 6.6.2.4. Non fare ipotesi sulle interfacce

Templates text should not make reference to widgets belonging to some debconf interfaces. Sentences like If you answer Yes... have no meaning for users of graphical interfaces that use checkboxes for boolean questions.

I modelli di frasi dovrebbero anche evitare di menzionare i valori predefiniti nella loro descrizione. Primo, perché questo è ridondante con i valori visualizzati dagli utenti. Inoltre, perché questi valori predefiniti possono essere diversi dalle scelte del maintainer (per esempio, quando il database debconf è stato preconfigurato).

Più in generale, cercare di evitare di riferirsi alle azioni dell'utente. Basta indicare i fatti.

#### 6.6.2.5. Non utilizzare la prima persona

You should avoid the use of first person (I will do this... or We recommend...). The computer is not a person and the Debconf templates do not speak for the Debian developers. You should use neutral construction. Those of you who already wrote scientific publications, just write your templates like you would write a scientific paper. However, try using the active voice if still possible, like Enable this if ... instead of This can be enabled if....

#### 6.6.2.6. Usare il genere neutro

As a way of showing our commitment to our diversity statement, please use gender-neutral constructions in your writing. This means avoiding pronouns like he/she when referring to a role (like "maintainer") whose gender is unknown. Instead, you should use the plural form (singular they).

### 6.6.3. Definizione dei campi dei modelli

This part gives some information which is mostly taken from the debconf-devel(7) manual page.

#### 6.6.3.1. Tipo

##### 6.6.3.1.1. stringa

Risultati in un campo di input nel quale l'utente può digitare qualsiasi frase.

##### 6.6.3.1.2. password

Richiede all'utente una password. La si usi con cautela; si sia consapevoli del fatto che la password che l'utente inserisce sarà scritta nel database di debconf. Si dovrebbe cancellare quel valore fuori dal database appena è possibile.

##### 6.6.3.1.3. booleano

Una scelta vero/falso. Ricordare: vero/falso, non si/no...

##### 6.6.3.1.4. seleziona

Una scelta tra una serie di valori. Le scelte devono essere specificate in un campo denominato «Choices». Separare i possibili valori con le virgole e gli spazi, in questo modo: `Scelte: sì, no, forse`.

Se le scelte sono stringhe traducibili, il campo «Choices» può essere contrassegnato come traducibile utilizzando `__Choices`. La doppia sottolineatura suddividerà ogni scelta in una stringa separata.

Il sistema `po-debconf` offre anche interessanti possibilità di marcare solamente alcune scelte come traducibili. Esempio:

    Template: foo/bar
    Type: Select
    #flag:translate:3
    __Choices: PAL, SECAM, Other
    _Description: TV standard:
     Please choose the TV standard used in your country.

In questo esempio, solo la stringa «Other» è traducibile, mentre altri sono acronimi che non devono essere tradotti. Quanto sopra esposto consente solo ad «Other» di essere inserito nei file PO e POT.

The debconf templates flag system offers many such possibilities. The po-debconf(7) manual page lists all these possibilities.

##### 6.6.3.1.5. multiselect

Come per la selezione del tipo di dato, ad eccezione di quando l'utente può scegliere un qualsiasi numero di elementi dall'elenco delle scelte (o scegliere nessuno di loro).

##### 6.6.3.1.6. nota

Piuttosto che essere una questione di per sé, questo tipo di dato indica una nota che può essere visualizzata all'utente. Dovrebbe essere usato solo per le note importanti che l'utente in realtà dovrebbe vedere, dato che debconf andrà incontro a grandi dolori per assicurarsi che l'utente la veda; arrestando l'installazione per consentire loro di premere un tasto persino inviandogli la nota tramite posta elettronica in alcuni casi.

##### 6.6.3.1.7. testo

Questo tipo è ora considerato obsoleto: non usarlo.

##### 6.6.3.1.8. errore

This type is designed to handle error messages. It is mostly similar to the note type. Front ends may present it differently (for instance, the dialog front end of cdebconf draws a red screen instead of the usual blue one).

Si consiglia di utilizzare questo tipo per ogni messaggio che necessita dell'attenzione dell'utente per una correzione di qualsiasi tipo.

#### 6.6.3.2. Descrizione: descrizione breve ed estesa

Le descrizioni dei modelli constano di due parti: breve ed estesa. La descrizione breve è nella linea «Description:» del modello.

La descrizione breve dovrebbe essere mantenuta breve (50 caratteri o giù di lì) in modo che possa essere accolta dalla maggior parte delle interfacce di debconf. Mantenerla breve aiuta anche i traduttori, considerato che normalmente le traduzioni tendono a finire per essere più lunghe rispetto all'originale.

The short description should be able to stand on its own. Some interfaces do not show the long description by default, or only if the user explicitly asks for it or even do not show it at all. Avoid things like: "What do you want to do?"

La descrizione breve non deve necessariamente essere un periodo completo. Questo fa parte della raccomandazione di mantenerla breve ed efficiente.

La descrizione estesa non deve ripetere la descrizione breve parola per parola. Se non è possibile pensare ad una descrizione lunga, quindi primo, si pensi un po' di più. Si condivida in debian-devel. Si chieda aiuto. Ci si iscriva ad un corso di scrittura! La descrizione estesa è importante. Se dopo tutto questo non è ancora possibile trovare qualcosa, la si lasci vuota.

La descrizione estesa dovrebbe usare periodi completi. I paragrafi devono essere brevi per migliorare la leggibilità. Non mescolare due idee nello stesso punto, piuttosto si usi un altro paragrafo.

Non si sia troppo prolissi. Gli utenti tendono a ignorare schermate troppo lunghe. 20 righe sono per esperienza un limite che non si dovrebbe oltrepassare, perché ciò significa che nella finestra di interfaccia classica, le persone avranno bisogno di scorrere e molte persone semplicemente non lo fanno.

La descrizione estesa non dovrebbe mai includere una domanda.

Per specifiche regole inerenti il tipo di template (string, boolean, etc), leggere qui di seguito.

#### 6.6.3.3. Scelte

This field should be used for select and multiselect types. It contains the possible choices that will be presented to users. These choices should be separated by commas.

#### 6.6.3.4. Default

Questo campo è facoltativo. Esso contiene la risposta predefinita per i modelli di periodi, di selezione singola e multipla. Per i modelli di selezione multipla, può contenere un elenco di scelte separate da virgole.

### 6.6.4. Template fields specific style guide

#### 6.6.4.1. Type field

Nessuna indicazione specifica eccetto: utilizzare il tipo appropriato, facendo riferimento alla sezione precedente.

#### 6.6.4.2. Il campo Description

Qui di seguito sono istruzioni specifiche per scrivere correttamente la descrizione (breve e lunga) a seconda del tipo di modello.

##### 6.6.4.2.1. Modelli di string/password

- La descrizione breve è un suggerimento e non un titolo. Evitare domande in stile suggerimento (indirizzo IP?) a favore di suggerimenti aperti (indirizzo IP:). Si consiglia l'uso dei due punti.

- La descrizione estesa è un complemento della descrizione breve. Nella parte estesa, si spieghi ciò che viene chiesto, piuttosto che riproporre la stessa domanda con parole più lunghe. Utilizzare frasi complete. Una scrittura concisa è fortemente sconsigliata.

##### 6.6.4.2.2. Modelli booleani

- The short description should be phrased in the form of a question, which should be kept short and should generally end with a question mark. Terse writing style is permitted and even encouraged if the question is rather long (remember that translations are often longer than original versions).

- Anche in questo caso, evitare il riferimento a specifici widget delle interfacce. Un errore comune per tali modelli è se si risponde con costrutti di tipo Yes.

##### 6.6.4.2.3. Selezione/Multiselezione

- The short description is a prompt and not a title. Do not use useless "Please choose..." constructions. Users are clever enough to figure out they have to choose something... :)

- La descrizione estesa completerà la descrizione breve. Può far riferimento alle scelte disponibili. Può anche indicare che l'utente può scegliere più di una tra le scelte disponibili, se il modello è di tipo selezione multipla (l'interfaccia spesso rende chiaro tutto ciò).

##### 6.6.4.2.4. Notes

- La descrizione breve dovrebbe essere considerata un titolo.

- La descrizione estesa è ciò che sarà visualizzato come una spiegazione più dettagliata della nota. Frasi, non scrittura sintetica.

- Do not abuse debconf. Notes are the most common way to abuse debconf. As written in the debconf-devel(7) manual page: it's best to use them only for warning about very serious problems. The `NEWS.Debian` or `README.Debian` files are the appropriate location for a lot of notes. If, by reading this, you consider converting your Note type templates to entries in `NEWS.Debian` or `README.Debian`, please consider keeping existing translations for the future.

#### 6.6.4.3. Campo Choises

Se le «Choises» sono suscettibili di cambiare spesso, considerare l'uso del trucco «__ Choices». Questo dividerà ogni singola scelta in una singola stringa, che aiuterà notevolmente i traduttori nel compiere il loro lavoro.

#### 6.6.4.4. Campo Default

If the default value for a select template is likely to vary depending on the user language (for instance, if the choice is a language choice), please use the _Default trick, documented in po-debconf 7.

This special field allows translators to put the most appropriate choice according to their own language. It will become the default choice when their language is used while your own mentioned Default Choice will be used when using English.

Do not use an empty default field. If you don't want to use default values, do not use Default at all.

If you use po-debconf (and you should; see Sii gentile con i traduttori), consider making this field translatable, if you think it may be translated.

Esempio, tratto dai modelli del pacchetto geneweb:

    Template: geneweb/lang
    Type: select
    __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)
    # This is the default choice. Translators may put their own language here
    # instead of the default.
    # WARNING : you MUST use the ENGLISH NAME of your language
    # For instance, the French translator will need to put French (fr) here.
    _Default: English[ translators, please see comment in PO files]
    _Description: Geneweb default language:

Note the use of brackets, which allow internal comments in debconf fields. Also note the use of comments, which will show up in files the translators will work with.

The comments are needed as the _Default trick is a bit confusing: the translators may put in their own choice.

## 6.7. Internazionalizzazione

This section contains global information for developers to make translators' lives easier. More information for translators and developers interested in internationalization are available in the Internationalisation and localisation in Debian documentation.

### 6.7.1. Gestione delle traduzioni debconf

Come gli autori di port, i traduttori hanno un compito difficile. Lavorano su molti pacchetti e devono collaborare con molti maintainer diversi. Inoltre, la maggior parte delle volte, non sono di madrelingua inglese, quindi si potrebbe dover essere particolarmente pazienti con loro.

The goal of `debconf` was to make package configuration easier for maintainers and for users. Originally, translation of debconf templates was handled with `debconf-mergetemplate`. However, that technique is now deprecated; the best way to accomplish `debconf` internationalization is by using the `po-debconf` package. This method is easier both for maintainer and translators; transition scripts are provided.

Using `po-debconf`, the translation is stored in `.po` files (drawing from `gettext` translation techniques). Special template files contain the original messages and mark which fields are translatable. When you change the value of a translatable field, by calling `debconf-updatepo`, the translation is marked as needing attention from the translators. Then, at build time, the `dh_installdebconf` program takes care of all the needed magic to add the template along with the up-to-date translations into the binary packages. Refer to the po-debconf(7) manual page for details.

### 6.7.2. Documentazione internazionalizzata

Internazionalizzare la documentazione è fondamentale per gli utenti, ma richiede molto lavoro. Non c'è modo di eliminare tutto quel lavoro, ma si possono rendere le cose più facili per i traduttori.

If you maintain documentation of any size, it is easier for translators if they have access to a source control system. That lets translators see the differences between two versions of the documentation, so, for instance, they can see what needs to be retranslated. It is recommended that the translated documentation maintain a note about what source control revision the translation is based on. An interesting system is provided by doc-check in the `debian-installer` package, which shows an overview of the translation status for any given language, using structured comments for the current revision of the file to be translated and, for a translated file, the revision of the original file the translation is based on. You might wish to adapt and provide that in your VCS area.

If you maintain XML or SGML documentation, we suggest that you isolate any language-independent information and define those as entities in a separate file that is included by all the different translations. This makes it much easier, for instance, to keep URLs up to date across multiple files.

Some tools (e.g. `po4a`, `poxml`, or the `translate-toolkit`) are specialized in extracting the translatable material from different formats. They produce PO files, a format quite common to translators, which permits seeing what needs to be re-translated when the translated document is updated.

## 6.8. Best practices for `debian/patches`

Debian packages might suffer from bugs in the upstream code that you need to deal with. In the source format “3.0 (quilt)” patches are stored in `debian/patches/` and automatically applied as listed in `debian/patches/series` when the source package is unpacked.

Patches should be documented following DEP-3.

Several tools exist to automate managing the patches. If you manage a source package outside of any Git repository, then your best option is likely `quilt`. Otherwise, you should consider to rely on Git's built-in features or on on the git packaging helper that you use (if any). In particular, for packages using `git-buildpackage`, you should use the `gbp pq` commands to manage the contents of the `debian/patches/` directory.

A single patch can be created with e.g. `git format-patch -1 d33286c` from a single commit. Avoid using git show as it lacks the full headers.

If the upstream fix is spread across multiple commits but makes sense to apply (and drop) in Debian as a single patch, one could use a command such as `git format-patch --stdout abc123..def456 > debian/patches/...` and append the `Bug` field only in the commit message of the first commit in the patch.

If one appends .patch to the url of a GitHub commit or Pull Request or GitLab commit or Merge Request, the resulting patch file is using this same format (as if it were generated by `git format-patch`).

Remember to always append a `Bug` header to the patch description so that a reader can follow the link to see where the bug was reported or patch submitted. If the purpose of the patch is to specifically divert from upstream permanently, append the header Forwarded: not-needed to the end of the description.

## 6.9. Situazioni comuni durante la pacchettizzazione

### 6.9.1. Pacchettizzazione utilizzando `autoconf`/`automake`

Mantenere i file `config.sub` e `config.guess` di `autoconf` aggiornati è fondamentale per gli autori di port, soprattutto su architetture più volatili. Alcune ottime pratiche di packaging per ogni pacchetto che usa `autoconf` e/o `automake` sono state sintetizzate in `/usr/share/doc/autotools-dev/README.Debian.gz` dal pacchetto `autotools-dev`. Si è vivamente incoraggiati a leggere questo file e di seguire le raccomandazioni in esso fornite.

### 6.9.2. Le librerie

Le librerie sono sempre difficili da pacchettizzare per vari motivi. La policy impone molti vincoli per facilitare il loro mantenimento e per assicurarsi che gli aggiornamenti siano i più semplici possibili quando una nuova versione viene pubblicata. Una rottura in una libreria può causare una rottura in decine di pacchetti dipendenti.

Good practices for library packaging have been grouped in the library packaging guide.

### 6.9.3. La documentazione

Assicurarsi di seguire la policy Policy sulla documentazione.

Se il pacchetto contiene la documentazione compilata a partire da XML o SGML, si consiglia di non includere il sorgente XML o SGML nel pacchetto binario. Se gli utenti vogliono il sorgente della documentazione, dovrebbero poter recuperare il pacchetto sorgente.

La policy specifica che la documentazione deve essere fornita in formato HTML. Si consiglia anche di inserire la documentazione in formato PDF e testo normale se conveniente e se è possibile output di discreta qualità. Tuttavia, non è in genere appropriato includere la versione in testo semplice della documentazione il cui formato sorgente è HTML.

La maggior parte dei manuali dovrebbe registrarsi con `doc-base` durante l'installazione. Si consulti la documentazione del pacchetto `doc-base` per ulteriori informazioni.

La policy di Debian (sezione 12.1) indica che le pagine del manuale dovrebbero accompagnare ogni programma, utility e la funzione e suggerirli per altri oggetti come file di configurazione. Se il lavoro che si sta pacchettizzando non ha queste pagine di manuale, si consideri la loro scrittura per l'inclusione nel pacchetto e di sottoporla allo sviluppatore originale.

The manpages do not need to be written directly in the troff format. Popular source formats are DocBook, POD and reST, which can be converted using `xsltproc`, `pod2man` and `rst2man` respectively. To a lesser extent, the `help2man` program can also be used to write a stub.

### 6.9.4. Specifici tipi di pacchetti

Vari tipi specifici di pacchetti hanno particolari sub-politiche e rispettive pratiche e regole per la pacchettizzazione:

- Perl related packages have a Perl policy; some examples of packages following that policy are `libdbd-pg-perl` (binary perl module) or `libmldbm-perl` (arch independent perl module).

- Python related packages have their Python policy; see `/usr/share/doc/python/python-policy.txt.gz` in the `python` package.

- I relativi pacchetti Emacs hanno la emacs policy.

- I relativi pacchetti Java hanno la loro java policy.

- OCaml related packages have their own policy, found in `/usr/share/doc/ocaml/ocaml_packaging_policy.gz` from the `ocaml` package. A good example is the `camlzip` source package.

- I pacchetti che forniscono XML o SGML DTD devono essere conformi alle indicazioni fornite nel pacchetto `sgml-base-doc`.

- I pacchetti Lisp si devono registrare con il `common-lisp-controller`, a proposito del quale si veda `/usr/share/doc/common-lisp-controller/README.packaging`.

- Rust packaging is described in the Debian Rust Team Book;.

- Packages providing services ("daemons") should be functional on a fresh install, to the extent that that is possible without compromising security (e.g. a web server should by default be up and running and serve a dummy page, but must otherwise not allow unauthenticated sensitive operations; consider whether to serve only on the localhost network interface, by default).

- Web application packages should aim to have their dependencies (including javascript) packaged separately, and should carry out whatever setup is necessary for basic and secure functionality out of the box (e.g. create a database, ship configs with reasonable defaults, install files in appropriate location with appropriate permissions, etc). For examples, look at how existing web applications are packaged, e.g. dfsg-new-queue for Go, gitlab for ruby on rails, node-shiny-server for NPM. diaspora-installer is a dummy package which downloads diaspora (also pulling in runtime dependencies as rubygems) and configures it to use PostgreSQL and Nginx.

### 6.9.5. Dati indipendenti dall'architettura

Non è raro avere una grande quantità di dati indipendenti dall'architettura pacchettizzati con un programma. Ad esempio, i file audio, una collezione di icone, modelli di wallpaper, o altri file grafici. Se la dimensione di questi dati è trascurabile rispetto alle dimensioni del resto del pacchetto, probabilmente è meglio tenere il tutto in un unico pacchetto.

However, if the size of the data is considerable, consider splitting it out into a separate, architecture-independent package (`_all.deb`). By doing this, you avoid needless duplication of the same data into ten or more .debs, one per each architecture. While this adds some extra overhead into the `Packages` files, it saves a lot of disk space on Debian mirrors. Separating out architecture-independent data also reduces processing time of `lintian` (see Strumenti per la pulizia di pacchetti) when run over the entire Debian archive.

### 6.9.6. Aver bisogno di una particolare localizzazione durante la compilazione

Se si ha bisogno di una certa localizzazione durante la compilazione, si può creare un file temporaneo con questo trucco:

Se si imposta `LOCPATH` all'equivalente di `/usr/lib/locale` e `LC_ALL` al nome del locale che si genera, si dovrebbe ottenere ciò che si desidera senza essere root. Qualcosa di simile a questo:

    LOCALE_PATH=debian/tmpdir/usr/lib/locale
    LOCALE_NAME=en_IN
    LOCALE_CHARSET=UTF-8

    mkdir -p $LOCALE_PATH
    localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET $LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET

    # Using the locale
    LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date

### 6.9.7. Rendere i pacchetti di transizione conformi a deborphan

Deborphan è un programma per aiutare gli utenti ad individuare quali pacchetti possono essere tranquillamente rimossi dal sistema, vale a dire quelli che non hanno pacchetti dipendenti da loro. Il funzionamento predefinito è di cercare solo all'interno delle sezioni libs e oldlibs, per dare la caccia a librerie inutilizzate. Ma quando viene passato l'argomento giusto, cerca di catturare altri pacchetti inutili.

For example, with `--guess-dummy`, `deborphan` tries to search all transitional packages which were needed for upgrade but which can now be removed. For that, it currently looks for the string dummy or transitional in their short description, though it would be better to search for both strings, as there are some dummy or transitional packages, which have other purposes.

So, when you are creating such a package, please make sure to add `transitional dummy package` to the short description to make this explicit. If you are looking for examples, just run: `apt-cache search .|grep dummy` or `apt-cache search .|grep transitional`.

Also, it is recommended to adjust its section to `oldlibs` and its priority to `optional` in order to ease `deborphan`'s job.

### 6.9.8. Buone pratiche per i file `.orig.tar.{gz,bz2,xz}`

Ci sono due tipi di tarball dei sorgenti originali: sorgente puro e sorgente originale ripacchettizzato.

#### 6.9.8.1. Sorgente puro

La caratteristica distintiva di un tarball sorgente incontaminato è che il `.orig.tar.{gz,bz2,xz}` è byte-per-byte identico a un tarball ufficialmente distribuito dall'autore originale. [1] Questo rende possibile l'utilizzo di checksum per verificare facilmente che tutte le modifiche tra la versione di Debian e quella originale siano contenute nel Debian diff. Inoltre, se il sorgente originale è enorme, gli autori originali e chiunque possieda già l'archivio originale possono risparmiare tempo di download, se vogliono ispezionare il pacchetto in dettaglio.

There are no universally accepted guidelines that upstream authors follow regarding the directory structure inside their tarball, but `dpkg-source` is nevertheless able to deal with most upstream tarballs as pristine source. Its strategy is equivalent to the following:

1. Si scompatta l'archivio in una cartella temporanea vuota facendo

       zcat path/to/packagename_upstream-version.orig.tar.gz | tar xf -

2. Se, dopo questo, la cartella temporanea non contiene nulla, ma una sola cartella e nessun altro file, `dpkg-source` rinomina quella cartella in packagename`-`upstream-version`(.orig)`. Il nome della più alta cartella nella tarball non ha importanza, ed è tralasciata.

3. In caso contrario, l'archivio originale deve essere stato confezionato senza una comune cartella di livello alto (vergogna sull'autore originale!). In questo caso, `dpkg-source` rinomina la cartella temporanea stessa in packagename`-`upstream-version`(.orig)`.

#### 6.9.8.2. Sorgente originale ripacchettizzato

Si dovrebbe caricare i pacchetti con un tarball sorgente puro, se possibile, ma ci sono vari motivi per cui potrebbe non essere possibile. Questo è il caso in cui se l'autore originale non distribuisce il sorgente come non completamente compresso in formato tar, o se il tarball originale contiene materiale non DFSG-free che è necessario rimuovere prima di caricare.

In questi casi, lo sviluppatore deve costruirsi un `.orig.tar.{gz,bz2,xz}` adatto. Ci si riferisce a un tale tarball come sorgente originale ripacchettizato. Si noti che un sorgente originale ripacchettizato è diverso da un pacchetto Debian nativo. Un sorgente originale ripacchettizato con modifiche specifiche per Debian ancora viene distribuito in un separato `.diff.gz` o `.debian.tar.{gz,bz2,xz}` e ha ancora un numero di versione composto da upstream-version e debian-version.

Ci possono essere casi in cui è auspicabile pacchettizzare nuovamente il sorgente anche se l'autore originale distribuisce un `.tar.{gz,bz2,xz}` che potrebbe in linea di principio essere utilizzato nella sua forma originaria. Il più ovvio è se un significativo risparmio di spazio può essere ottenuto ricomprimendo l'archivio tar o rimuovendo genuinamente dell'inutile fuffa dall'archivio originale. Si usi la propria discrezione qui, ma si sia pronti a difendere la propria decisione se si pacchettizza nuovamente il sorgente che poteva esser puro.

Un `.orig.tar.{gz,bz2,xz}` ripacchettizzato

1. should be documented in the resulting source package. Detailed information on how the repackaged source was obtained, and on how this can be reproduced should be provided in `debian/copyright`, ideally in a way that can be done automatically with uscan. If that really doesn't work, at least provide a `get-orig-source` target in your `debian/rules` file that repeats the process, even though that was actually deprecated in the 4.1.4 version of the Debian policy.

2. non dovrebbe contenere qualsiasi tipo di file che non proviene dall'autore originale, o il cui contenuto è stato modificato. [2]

3. should, except where impossible for legal reasons, preserve the entire building and portability infrastructure provided by the upstream author. For example, it is not a sufficient reason for omitting a file that it is used only when building on MS-DOS. Similarly, a `Makefile` provided by upstream should not be omitted even if the first thing your `debian/rules` does is to overwrite it by running a configure script.

   (Motivazione: È comune per gli utenti Debian che hanno bisogno di compilare software per piattaforme non-Debian prendere il sorgente da uno dei mirror Debian piuttosto che cercare di individuare un punto canonico di distribuzione originale).

4. may use packagename`-`upstream-version`+dfsg` (or any other suffix which is added to the tarball name) as the name of the top-level directory in its tarball. This makes it possible to distinguish pristine tarballs from repackaged ones.

5. should be compressed with `xz` (or `gzip` or `bzip`) with maximal compression.

#### 6.9.8.3. Modifica dei file binari

Sometimes it is necessary to change binary files contained in the original tarball, or to add binary files that are not in it. This is fully supported when using source packages in “3.0 (quilt)” format; see the dpkg-source(1) manual page for details. When using the older format “1.0”, binary files can't be stored in the `.diff.gz` so you must store a `uuencode`d (or similar) version of the file(s) and decode it at build time in `debian/rules` (and move it in its official location).

### 6.9.9. Buone pratiche per i pacchetti di debug

A debug package is a package that contains additional information that can be used by `gdb`. Since Debian binaries are stripped by default, debugging information, including function names and line numbers, is otherwise not available when running `gdb` on Debian binaries. Debug packages allow users who need this additional debugging information to install it without bloating a regular system with the information.

The debug packages contain separated debugging symbols that `gdb` can find and load on the fly when debugging a program or library. The convention in Debian is to keep these symbols in `/usr/lib/debug/`path, where path is the path to the executable or library. For example, debugging symbols for `/usr/bin/foo` go in `/usr/lib/debug/usr/bin/foo`, and debugging symbols for `/usr/lib/libfoo.so.1` go in `/usr/lib/debug/usr/lib/libfoo.so.1`.

#### 6.9.9.1. Automatically generated debug packages

Debug symbol packages can be generated automatically for any binary package that contains executable binaries, and except for corner cases, it should not be necessary to use the old manually generated ones anymore. The package name for a automatic generated debug symbol package ends in `-dbgsym`.

The `dbgsym` packages are not installed into the regular archives, but in dedicated archives. That means, if you need the debug symbols for debugging, you need to add this archives to your apt configuration and then install the `dbgsym` package you are interested in. Please read https://wiki.debian.org/HowToGetABacktrace on how to do that.

#### 6.9.9.2. Manual -dbg packages

Before the advent of the automatic `dbgsym` packages, debug packages needed to be manually generated. The name of a manual debug packages ends in `-dbg`. It is recommended to migrate such old legacy packages to the new `dbgsym` packages whenever possible. The procedure to convert your package is described in https://wiki.debian.org/AutomaticDebugPackages but the gist is to use the `--dbgsym-migration='pkgname-dbg (<< currentversion~)'` switch of the `dh_strip` command.

However, sometimes it is not possible to convert to the new `dbgsym` packages, or you will encounter the old manual -dbg packages in the archives, so you might need to deal with them. It is not recommended to create manual -dbg packages for new packages, except if the automatic ones won't work for some reason.

One reason could be that debug packages contains an entire special debugging build of a library or other binary. However, usually separating debugging information from the already built binaries is sufficient and will also save space and build time.

This is the case, for example, for debugging symbols of Python extensions. For now the right way to package Python extension debug symbols is to use `-dbg` packages as described in https://wiki.debian.org/Python/DbgBuilds.

To create `-dbg` packages, the package maintainer has to explicitly specify them in `debian/control`.

The debugging symbols can be extracted from an object file using `objcopy --only-keep-debug`. Then the object file can be stripped, and `objcopy --add-gnu-debuglink` used to specify the path to the debugging symbol file. objcopy 1 explains in detail how this works.

Si noti che il pacchetto di debug dovrebbe dipendere dal pacchetto per il quale fornisce i simboli di debug e questa dipendenza dovrebbe essere versionata. Per esempio:

    Depends: libfoo (= ${binary:Version})

The `dh_strip` command in `debhelper` supports creating debug packages, and can take care of using `objcopy` to separate out the debugging symbols for you. If your package uses `debhelper/9.20151219` or newer, you don't need to do anything. `debhelper` will generate debug symbol packages (as `package`-dbgsym) for you with no additional changes to your source package.

### 6.9.10. Buone pratiche per i metapacchetti

Un metapacchetto è un pacchetto per lo più vuoto che rende facile installare un insieme coerente di pacchetti che possono evolvere nel tempo. Realizza ciò creando una dipendenza per tutti i pacchetti dell'insieme. Grazie alla potenza di APT, il maintainer del metapacchetto può sistemare le dipendenze e il sistema dell'utente otterrà automaticamente i pacchetti supplementari. I pacchetti eliminati che sono stati installati automaticamente verranno contrassegnati come candidati alla rimozione (e saranno anche rimossi automaticamente da `aptitude`). `gnome` e `linux-image-amd64` sono due esempi di metapacchetti (compilati dai pacchetti sorgente meta-gnome2 e `linux-latest`).

The long description of the meta-package must clearly document its purpose so that the user knows what they will lose if they remove the package. Being explicit about the consequences is recommended. This is particularly important for meta-packages that are installed during initial installation and that have not been explicitly installed by the user. Those tend to be important to ensure smooth system upgrades and the user should be discouraged from uninstalling them to avoid potential breakages.

[1]

We cannot prevent upstream authors from changing the tarball they distribute without also incrementing the version number, so there can be no guarantee that a pristine tarball is identical to what upstream currently distributing at any point in time. All that can be expected is that it is identical to something that upstream once did distribute. If a difference arises later (say, if upstream notices that they weren't using maximal compression in their original distribution and then re-`gzip` it), that's just too bad. Since there is no good way to upload a new `.orig.tar.{gz,bz2,xz}` for the same version, there is not even any point in treating this situation as a bug.

[2]

As a special exception, if the omission of non-free files would lead to the source failing to build without assistance from the Debian diff, it might be appropriate to instead edit the files, omitting only the non-free parts of them, and/or explain the situation in a `README.source` file in the root of the source tree. But in that case please also urge the upstream author to make the non-free components easier to separate from the rest of the source.