mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
Fix multiple identation errors
This commit is contained in:
parent
2a0df6b2a9
commit
92db66e139
@ -5,7 +5,6 @@ language: it-IT
|
|||||||
version: 1.0.0
|
version: 1.0.0
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
||||||
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
||||||
- gemnasium = "https://gemnasium.com/"
|
- gemnasium = "https://gemnasium.com/"
|
||||||
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
||||||
@ -34,7 +33,7 @@ version: 1.0.0
|
|||||||
Cos'è un changelog?
|
Cos'è un changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Un changelog è un file che contiene una lista curata e ordinata cronologicamente
|
Un changelog è un file che contiene una lista curata e ordinata cronologicamente
|
||||||
delle modifiche degne di nota per ogni versione di un progetto.
|
delle modifiche degne di nota per ogni versione di un progetto.
|
||||||
|
|
||||||
%h3#why
|
%h3#why
|
||||||
@ -42,7 +41,7 @@ version: 1.0.0
|
|||||||
Perché tenere un changelog?
|
Perché tenere un changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche
|
Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche
|
||||||
importanti sono state fatte tra ogni release (o versione) del progetto.
|
importanti sono state fatte tra ogni release (o versione) del progetto.
|
||||||
|
|
||||||
%h3#who
|
%h3#who
|
||||||
@ -50,7 +49,7 @@ version: 1.0.0
|
|||||||
Chi ha bisogno di un changelog?
|
Chi ha bisogno di un changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Le persone ne hanno bisogno. Che si tratti di consumatori o di sviluppatori, gli utenti finali
|
Le persone ne hanno bisogno. Che si tratti di consumatori o di sviluppatori, gli utenti finali
|
||||||
del software sono persone interessate a ciò che avviene in esso.
|
del software sono persone interessate a ciò che avviene in esso.
|
||||||
Se il software è cambiato, allora le persone vogliono sapere come e perché.
|
Se il software è cambiato, allora le persone vogliono sapere come e perché.
|
||||||
|
|
||||||
@ -75,9 +74,9 @@ version: 1.0.0
|
|||||||
%li
|
%li
|
||||||
L'ultima versione viene prima.
|
L'ultima versione viene prima.
|
||||||
%li
|
%li
|
||||||
Viene mostrata la data di release di ogni versione.
|
Viene mostrata la data di release di ogni versione.
|
||||||
%li
|
%li
|
||||||
Si dichiara se il progetto segue il #{link_to "Versionamento Semantico", semver}.
|
Si dichiara se il progetto segue il #{link_to "Versionamento Semantico", semver}.
|
||||||
|
|
||||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||||
%h4#types Tipologie di cambiamenti
|
%h4#types Tipologie di cambiamenti
|
||||||
@ -101,7 +100,7 @@ version: 1.0.0
|
|||||||
%li
|
%li
|
||||||
%code Security
|
%code Security
|
||||||
per invitare gli utilizzatori ad aggiornare in caso di vulnerabilità.
|
per invitare gli utilizzatori ad aggiornare in caso di vulnerabilità.
|
||||||
|
|
||||||
.effort
|
.effort
|
||||||
|
|
||||||
%h3#effort
|
%h3#effort
|
||||||
@ -109,8 +108,8 @@ version: 1.0.0
|
|||||||
Come posso ridurre gli sforzi necessari a mantenere un changelog?
|
Come posso ridurre gli sforzi necessari a mantenere un changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Tieni una sezione <code>Unreleased</code> in cima al changelog in modo da tenere traccia
|
Tieni una sezione <code>Unreleased</code> in cima al changelog in
|
||||||
dei cambiamenti imminenti.
|
modo da tenere traccia dei cambiamenti imminenti.
|
||||||
|
|
||||||
%p Questo serve per due scopi:
|
%p Questo serve per due scopi:
|
||||||
|
|
||||||
@ -118,14 +117,16 @@ version: 1.0.0
|
|||||||
%li
|
%li
|
||||||
Le persone possono vedere quali modifiche si possono aspettare nelle future release.
|
Le persone possono vedere quali modifiche si possono aspettare nelle future release.
|
||||||
%li
|
%li
|
||||||
Ad una nuova release, si deve solo spostare i cambiamenti della sezione
|
Ad una nuova release, si deve solo spostare i cambiamenti della sezione
|
||||||
`"Unreleased"` in una nuova sezione con il suo numero di versione.
|
`"Unreleased"` in una nuova sezione con il suo numero di versione.
|
||||||
|
|
||||||
.bad-practices
|
.bad-practices
|
||||||
%h3#bad-practices
|
%h3#bad-practices
|
||||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||||
I changelog possono essere cattivi?
|
I changelog possono essere cattivi?
|
||||||
|
|
||||||
%p Si. Ecco alcuni modi in cui possono essere meno utili.
|
%p Si. Ecco alcuni modi in cui possono essere meno utili.
|
||||||
|
|
||||||
%h4#log-diffs
|
%h4#log-diffs
|
||||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||||
Commit log diffs
|
Commit log diffs
|
||||||
@ -136,11 +137,11 @@ version: 1.0.0
|
|||||||
modifiche della documentazione, etc.
|
modifiche della documentazione, etc.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Lo scopo di un commit è quello di documentare un passo nell'evoluzione
|
Lo scopo di un commit è quello di documentare un passo nell'evoluzione
|
||||||
del codice sorgente. Alcuini progetti ripuliscono i commit, altri non lo fanno.
|
del codice sorgente. Alcuini progetti ripuliscono i commit, altri non lo fanno.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Lo scopo di una voce changelog è quello di documentare le differenze rilevanti,
|
Lo scopo di una voce changelog è quello di documentare le differenze rilevanti,
|
||||||
spesso attraverso commit mulptipli, per comunicarli in mdo chiaro agli utenti finali.
|
spesso attraverso commit mulptipli, per comunicarli in mdo chiaro agli utenti finali.
|
||||||
|
|
||||||
%h4#ignoring-deprecations
|
%h4#ignoring-deprecations
|
||||||
@ -149,11 +150,11 @@ version: 1.0.0
|
|||||||
%p
|
%p
|
||||||
Quando le persone aggiornano da una versione ad un'altra,
|
Quando le persone aggiornano da una versione ad un'altra,
|
||||||
dovrebbe essere dolorosamente chiaro quando qualcosa si romperà.
|
dovrebbe essere dolorosamente chiaro quando qualcosa si romperà.
|
||||||
Dovrebbe essere possibile eseguire l'aggiornamento a una versione
|
Dovrebbe essere possibile eseguire l'aggiornamento a una versione
|
||||||
che elenca le deprecazioni, rimuove ciò che è deprecato, quindi
|
che elenca le deprecazioni, rimuove ciò che è deprecato, quindi
|
||||||
aggiorna alla versione in cui le deprecazioni diventano rimozioni.
|
aggiorna alla versione in cui le deprecazioni diventano rimozioni.
|
||||||
%p
|
%p
|
||||||
Se non fai nient'altro elenca le deprecazioni, le rimozioni e
|
Se non fai nient'altro elenca le deprecazioni, le rimozioni e
|
||||||
qualsiasi altro cambiamento nel tuo changelog.
|
qualsiasi altro cambiamento nel tuo changelog.
|
||||||
%h4#confusing-dates
|
%h4#confusing-dates
|
||||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||||
@ -161,14 +162,14 @@ version: 1.0.0
|
|||||||
|
|
||||||
%p
|
%p
|
||||||
Negli Stati Uniti si mette prima il mese nelle date (<code>06-02-2012</code> sta per
|
Negli Stati Uniti si mette prima il mese nelle date (<code>06-02-2012</code> sta per
|
||||||
il 2 Giugno 2012), mentre molte persone nel resto del mondo scrivono un
|
il 2 Giugno 2012), mentre molte persone nel resto del mondo scrivono un
|
||||||
robotico <code>2 June 2012</code>, ma lo pronunciano diversamente.
|
robotico <code>2 June 2012</code>, ma lo pronunciano diversamente.
|
||||||
<code>2012-06-02</code> funziona con la logica dal più grande al più piccolo,
|
<code>2012-06-02</code> funziona con la logica dal più grande al più piccolo,
|
||||||
non ha sovrapposizioni ambigue con altri formati di date, ed è uno #{link_to "ISO standard", iso}.
|
non ha sovrapposizioni ambigue con altri formati di date, ed è uno #{link_to "ISO standard", iso}.
|
||||||
Per tutti questi motivi, è il formato di date raccomandato per i changelog.
|
Per tutti questi motivi, è il formato di date raccomandato per i changelog.
|
||||||
|
|
||||||
%aside
|
%aside
|
||||||
C'è di più. Aiutatemi a collezionare questi anti-modelli
|
C'è di più. Aiutatemi a collezionare questi anti-modelli
|
||||||
= link_to "aprendo un issue", issues
|
= link_to "aprendo un issue", issues
|
||||||
o una pull request.
|
o una pull request.
|
||||||
|
|
||||||
@ -181,14 +182,14 @@ version: 1.0.0
|
|||||||
Esiste un formato standard per i changelog?
|
Esiste un formato standard per i changelog?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Non esattamente. Esistono le linee guida GNU sullo stile dei changelog, oppure
|
Non esattamente. Esistono le linee guida GNU sullo stile dei changelog, oppure
|
||||||
i due lunghi paragrafi nel documento di GNU NEWS denominato "guideline". Entrambe
|
i due lunghi paragrafi nel documento di GNU NEWS denominato "guideline". Entrambe
|
||||||
sono inadeguate o insufficienti.
|
sono inadeguate o insufficienti.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Questo progetto vuole essere
|
Questo progetto vuole essere
|
||||||
= link_to "una migliore convenzione per i file changelog.", changelog
|
= link_to "una migliore convenzione per i file changelog.", changelog
|
||||||
Per questo motivo osserviamo le migliori pratiche della comunità open source
|
Per questo motivo osserviamo le migliori pratiche della comunità open source
|
||||||
e le portiamo avanti.
|
e le portiamo avanti.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
@ -205,41 +206,48 @@ version: 1.0.0
|
|||||||
<code>HISTORY</code>, <code>NEWS</code> o <code>RELEASES</code>.
|
<code>HISTORY</code>, <code>NEWS</code> o <code>RELEASES</code>.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Mentre è facile pensare che il nome del tuo file changelog
|
Mentre è facile pensare che il nome del tuo file changelog
|
||||||
non sia poi così importante, perchè non rendere facile la
|
non sia poi così importante, perchè non rendere facile la
|
||||||
vita ai tuoi utenti, usando sempre lo stesso nome?
|
vita ai tuoi utenti, usando sempre lo stesso nome?
|
||||||
|
|
||||||
%h4#github-releases
|
%h4#github-releases
|
||||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||||
Cosa dire delle GitHub Releases?
|
Cosa dire delle GitHub Releases?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
È una bella iniziativa. #{link_to "Releases", ghr} può essere usato
|
È una bella iniziativa. #{link_to "Releases", ghr} può essere usato
|
||||||
per rendere semplice i git tags (per esempio il nome del tag <code>v1.0.0</code>)
|
per rendere semplice i git tags (per esempio il nome del tag
|
||||||
All'interno di note di rilascio ben dettagliate si possono aggiungere le note manualmente oppure è possibile
|
<code>v1.0.0</code>) All'interno di note di rilascio ben dettagliate
|
||||||
utilizzare le note dei messaggi dei git tag inserendole dentro nelle note di rilascio.
|
si possono aggiungere le note manualmente oppure è possibile
|
||||||
j
|
utilizzare le note dei messaggi dei git tag inserendole dentro nelle
|
||||||
|
note di rilascio.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
GitHub Releases crea un changelog non-portable che può essere solo
|
GitHub Releases crea un changelog non-portable che può essere solo
|
||||||
visualizzato dagli utenti nel contesto di GitHub. È possibile farlo
|
visualizzato dagli utenti nel contesto di GitHub. È possibile farlo
|
||||||
apparire molto simile al formato di Keep a Changelog, tuttavia tende
|
apparire molto simile al formato di Keep a Changelog, tuttavia tende
|
||||||
ad essere un po' più complicato.
|
ad essere un po' più complicato.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
La versione corrente di GitHub Releases risulta inoltre probabilmente
|
La versione corrente di GitHub Releases risulta inoltre
|
||||||
poco rilevante per gli utenti finali, a differenza dei tipici file maiuscoli
|
probabilmente poco rilevante per gli utenti finali, a differenza dei
|
||||||
(<code>README</code>, <code>CONTRIBUTING</code>, etc.). Un altro problema
|
tipici file maiuscoli (<code>README</code>,
|
||||||
minore è che l'interfaccia non offre attualmente link per la
|
<code>CONTRIBUTING</code>, etc.). Un altro problema minore è che
|
||||||
creazione di log tra ciascuna release.
|
l'interfaccia non offre attualmente link per la creazione di log tra
|
||||||
|
ciascuna release.
|
||||||
|
|
||||||
%h4#automatic
|
%h4#automatic
|
||||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||||
I changelog possono essere analizzati automaticamente?
|
I changelog possono essere analizzati automaticamente?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
È difficile, perché le persone usano formati e nomi di file profondamente diversi.
|
È difficile, perché le persone usano formati e nomi di file
|
||||||
|
profondamente diversi.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
#{link_to "Vandamme", vandamme} è una Ruby gem
|
#{link_to "Vandamme", vandamme} è una Ruby gem creata dal team
|
||||||
creata dal team #{link_to "Gemnasium", gemnasium} ed è in grado di fare il parsing dei
|
#{link_to "Gemnasium", gemnasium} ed è in grado di fare il parsing dei
|
||||||
change log di molti (ma non tutti) i progetti open source.
|
change log di molti (ma non tutti) i progetti open source.
|
||||||
|
|
||||||
|
|
||||||
%h4#yanked
|
%h4#yanked
|
||||||
@ -247,17 +255,18 @@ version: 1.0.0
|
|||||||
Cosa sono le release "yanked"?
|
Cosa sono le release "yanked"?
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Le release "yanked" sono versioni che sono state rimosse a causa di bug seri
|
Le release "yanked" sono versioni che sono state rimosse a causa di
|
||||||
o problemi di sicurezza. Spesso queste versioni non appaiono nei change
|
bug seri o problemi di sicurezza. Spesso queste versioni non
|
||||||
log. Invece dovrebbero esserci, nel seguente modo:
|
appaiono nei change log. Invece dovrebbero esserci, nel seguente
|
||||||
|
modo:
|
||||||
|
|
||||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||||
|
|
||||||
%p
|
%p
|
||||||
L'etichetta <code>[YANKED]</code> è in maiuscolo per un motivo.
|
L'etichetta <code>[YANKED]</code> è in maiuscolo per un motivo.
|
||||||
È importante che le persone la notino.
|
È importante che le persone la notino.
|
||||||
Poiché è racchiusa tra parentesi quadre è anche
|
Poiché è racchiusa tra parentesi quadre è anche
|
||||||
più semplice da riconoscere nel parsing automatizzato.
|
più semplice da riconoscere nel parsing automatizzato.
|
||||||
|
|
||||||
|
|
||||||
%h4#rewrite
|
%h4#rewrite
|
||||||
@ -266,13 +275,13 @@ version: 1.0.0
|
|||||||
|
|
||||||
%p
|
%p
|
||||||
Certo. Ci sono sempre buoni motivi per migliorare un changelog. Io apro regolarmente
|
Certo. Ci sono sempre buoni motivi per migliorare un changelog. Io apro regolarmente
|
||||||
delle pull request per aggiungere release mancanti ai progetti open source che non mantengono
|
delle pull request per aggiungere release mancanti ai progetti open source che non mantengono
|
||||||
correttamente i changelog.
|
correttamente i changelog.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
È anche possibile che si scopra di aver dimenticato di annotare una modifica
|
È anche possibile che si scopra di aver dimenticato di annotare una modifica
|
||||||
non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare
|
non retro-compatibile nelle note per una versione. Ovviamente è importante aggiornare
|
||||||
il changelog in questo caso.
|
il changelog in questo caso.
|
||||||
|
|
||||||
%h4#contribute
|
%h4#contribute
|
||||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||||
@ -280,11 +289,11 @@ version: 1.0.0
|
|||||||
|
|
||||||
%p
|
%p
|
||||||
Questo documento non è la <strong>verità assoluta</strong>; è solo la mia attenta
|
Questo documento non è la <strong>verità assoluta</strong>; è solo la mia attenta
|
||||||
opinione, arricchita dalle informazioni ed esempi che ho raccolto.
|
opinione, arricchita dalle informazioni ed esempi che ho raccolto.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che
|
Questo è perché voglio che la nostra comunità raggiunga un consenso. Credo che
|
||||||
la discussione sia importante almeno quanto il risultato finale.
|
la discussione sia importante almeno quanto il risultato finale.
|
||||||
|
|
||||||
%p
|
%p
|
||||||
Quindi per favore <strong>#{link_to "partecipate e dateci dentro", gh}</strong>.
|
Quindi per favore <strong>#{link_to "partecipate e dateci dentro", gh}</strong>.
|
||||||
|
Loading…
x
Reference in New Issue
Block a user