openSUSE:Creare file delle modifiche RPM

(Reindirizzamento da openSUSE:Howto write good changes)
Il presente articolo fornisce alcuni suggerimenti da parte del team review di openSUSE su come scrivere voci con una buona forma e utili nel file delle modifiche.

Sezione log delle modifiche (%changelog)

Ogni volta che si fanno modifiche al proprio pacchetto, si deve aggiungere una voce al log delle modifiche. Ciò è importante non solo per avere un'idea della storia pregressa di un pacchetto, ma anche per consentire a utenti, packager e addetti al controllo di qualità di sapere facilmente quali modifiche sono state introdotte.

Open Build Service usa un file a parte per registrare le modifiche apportate al pacchetto. Questo file ha lo stesso nome del file spec, ma con suffisso .changes al posto del suffisso .spec. Le voci relative al log delle modifiche devono essere in ordine cronologico. Le voci più recenti aggiunte al changelog compaiono in elenco prima di quelle meno recenti, per cui la prima voce in alto è quella più recente di tutte. Non si deve modificare alcun elemento già presente (in cui per elemento si intende del testo racchiuso tra "----------)", se si è già fatto il "check in" del pacchetto sul repository ufficiale (aggiornando quindi il progetto del repository ufficiale, ovvero openSUSE:Factory). Piccole correzioni ad errori di battitura e refusi sono invece accettabili. Allo stesso modo si possono aggiungere nuovi elementi, se inframezzati tra quelli vecchi. Questo consente di sviluppare i pacchetti in più di un ramo alla volta.

Le voce inserite in questo file delle modifiche sono strutturate e formattate nel modo seguente:

-------------------------------------------------------------------
Tue Apr 22 20:54:26 UTC 2011 - your@email.com

- level 1 bullet point; (le descrizioni lunghe
  dovrebbero venire contratte automaticamente)
  + level 2 bullet point; (le descrizioni lunghe
    dovrebbero venire contratte automaticamente)
  + another l2 bullet point
- another l1 bullet point

Nota: La lunghezza massima raccomandata per linea è di 67 caratteri (uguale a quella della linea tratteggiata/separatore). Gli elenchi puntati di terzo livello o superiore non sono implementati, per cui ad essi non verrà applicata alcuna formattazione speciale.

Un normale aggiornamento alla versione x.y.z potrebbe assomigliare a:

-------------------------------------------------------------------
Tue Apr 22 20:54:26 UTC 2013 - tuoindirizzo@email.com

- Update to version x.y.z:
  + bling and changes from upstream for that version
  + just the relevant parts, no info about other OS
  + and keep it as short as possible
- Added new BuildRequires glibc-devel: new dependency
- Do magic trick in install section to overcome installation failure
- add foobar-fix-ham.patch: <give a reason>
- add foobar-remove-spam.patch: <give a reason>
- modify foobar-autotools.patch: <give a reason>
- remove foobar-libpng15-compat.patch: <give a reason>  
- ... (other changes done to the package)

Formato generale:

  • Inizia con gli aggiornamenti di versione, incluse le informazioni riguardo l'aggiornamento
  • Riporta le modifiche generali al file .spec; due ragioni per farlo:
    • Documentare le modifiche per i cambiamenti futuri del pacchetto. Può aiutare a determinare se qualche hack è ancora necessario (eventuali hack nel file .spec dovrebbero comunque essere accompagnati da un commento) e quando è stato aggiunto.
    • Facilitare il compito dei reviewer: una breve spiegazione delle ragioni del proprio operato può aiutare ad evitare fastidiosi rifiuti ("decline" della richiesta) a causa di incomprensioni.

Correzione di bug, implementazione di funzionalità

Ogni volta che viene corretto un bug (o implementata una funzionalità), è necessario citare il numero di bug tra le modifiche. Dato che le modifiche dovrebbero essere accompagnate da un resoconto sul bagzilla del progetto originale (o upstream), è meglio aggiungere un prefisso davanti ad ogni numero, in tal modo le altre persone sapranno dove reperire le informazione di cui necessitano.

Prefisso Bug tracker
bnc# bugzilla.novell.com
fate# fate.suse.com
bko# bugzilla.kernel.org
kde# bugs.kde.org
bgo# bugzilla.gnome.org
bmo# bugzilla.mozilla.org

L'elenco completo è disponibile nella pagina con la raccolta delle abbreviazioni attualmente in uso.

Nel caso in cui il problema segnalato fosse accompagnato da qualche codice identificativo esterno, come il numero di revisione CVE, anche quest'ultimo dovrà entrare a far parte del log delle modifiche. Ci sono vari modi di strutturare la notifica (ovviamente in inglese):

   - update to Firefox 13.0 (bnc#765204)
     + MFSA 2012-34/CVE-2012-1938/CVE-2012-1937/CVE-2011-3101
       Miscellaneous memory safety hazards
  - Fix string quoting.  [bnc#666416]
  - Add xz BuildRequires because we can't build a package for a
    xz-compressed tarball without explicitly specifying that... See
    bnc#697467 for more details.
  - fix bnc#595144 - Compiled binary in ant

Aggiornamenti di pacchetto

In caso di un aggiornamento di pacchetto la nuova versione dovrà essere citata tra le modifiche. È spesso utile fornire alcune informazioni di base sulle modifiche, ricavate dal file delle modifiche (il "changelog") del rilascio originale (il rilascio "upstream"). Nel caso l'upstream non le fornisse, questa informazione dovrà comunque essere riportata nel file .changes, per esempio:

 - update to foo 1.2.3: no changelog available
 - update to Firefox 13.0.1
   + bugfix release

Modifiche per le patch

Tutte le modifiche nelle patch devono seguire le linee guida per le patch. È sempre una buona idea aggiungere il nome della patch in coda alla riga che descrive la correzione (il fix).

 - fix segfault on load incorrect document (bnc#123456)
   + foo-1.2.4-buffer-owerflow.patch
 - update to Firefox 7 (bnc#720264)
   + removed obsolete mozilla-cairo-lcd.patch (upstream)