mirror of
https://github.com/olivierlacan/keep-a-changelog.git
synced 2025-07-29 16:54:12 +02:00
Create 1.0.0/index.html.haml
The beginning of translation
This commit is contained in:
Michele Castoldi
GitHub
parent
e82086e32d
commit
e4d0832e6b
302
source/it-IT/1.0.0/index.html.haml
Normal file
302
source/it-IT/1.0.0/index.html.haml
Normal file
@ -0,0 +1,302 @@
|
||||
---
|
||||
description: Keep a Changelog
|
||||
title: Keep a Changelog
|
||||
language: it-IT
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
|
||||
- changelog = "https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md"
|
||||
- gemnasium = "https://gemnasium.com/"
|
||||
- gh = "https://github.com/olivierlacan/keep-a-changelog"
|
||||
- issues = "https://github.com/olivierlacan/keep-a-changelog/issues"
|
||||
- semver = "http://semver.org/"
|
||||
- shields = "http://shields.io/"
|
||||
- thechangelog = "http://5by5.tv/changelog/127"
|
||||
- vandamme = "https://github.com/tech-angels/vandamme/"
|
||||
- iso = "http://www.iso.org/iso/home/standards/iso8601.htm"
|
||||
- ghr = "https://help.github.com/articles/creating-releases/"
|
||||
|
||||
.header
|
||||
.title
|
||||
%h1 Tenere un Changelog
|
||||
%h2 Non lasciare che i tuoi amici facciano copia incolla dei git logs nei changelogs.
|
||||
|
||||
= link_to changelog do
|
||||
Versione
|
||||
%strong= current_page.metadata[:page][:version]
|
||||
|
||||
%pre.changelog= File.read("CHANGELOG.md")
|
||||
|
||||
.answers
|
||||
%h3#what
|
||||
%a.anchor{ href: "#what", aria_hidden: "true" }
|
||||
Cos'è un changelog?
|
||||
|
||||
%p
|
||||
Un change log è un file che contiene una lista curata e ordinata cronologicamente
|
||||
delle modifiche degne di nota per ogni versione di un progetto.
|
||||
|
||||
%h3#why
|
||||
%a.anchor{ href: "#why", aria_hidden: "true" }
|
||||
Perché tenere un changelog?
|
||||
|
||||
%p
|
||||
Per rendere facile agli utilizzatori e contribuenti vedere con precisione quali modifiche
|
||||
importanti sono state fatte tra ogni release (o versione) del progetto.
|
||||
|
||||
%h3#who
|
||||
%a.anchor{ href: "#who", aria_hidden: "true" }
|
||||
Chi ha bisogno di un changelog?
|
||||
|
||||
%p
|
||||
Le persone ne hanno bisogno. Che si tratti di consumatori o di sviluppatori, gli utenti finali
|
||||
del software sono persone interessate di ciò che è nel software.
|
||||
Se il software è cambiato, allora le persone vogliono sapere perché e come.
|
||||
|
||||
.good-practices
|
||||
%h3#how
|
||||
%a.anchor{ href: "#how", aria_hidden: "true" }
|
||||
Come posso fare un buon changelog?
|
||||
|
||||
%h4#principles
|
||||
%a.anchor{ href: "#principles", aria_hidden: "true" }
|
||||
Linee guida
|
||||
|
||||
%ul
|
||||
%li
|
||||
Changelogs sono <em>per le persone</em>, non per le macchine.
|
||||
%li
|
||||
Dovrebbe essere una voce per ogni singola versione.
|
||||
%li
|
||||
Gli stessi tipi di modifiche dovrebbero essere raggruppati.
|
||||
%li
|
||||
Versioni e sezioni dovrebbero essere collegabili.
|
||||
%li
|
||||
L'ultima versione viene prima.
|
||||
%li
|
||||
Viene mostrata la data di release di ogni versione.
|
||||
%li
|
||||
Si dichiara se il progetto segue il #{link_to "Versionamento Semantico", semver}.
|
||||
|
||||
%a.anchor{ href: "#types", aria_hidden: "true" }
|
||||
%h4#types Tipologie di cambiamenti
|
||||
|
||||
%ul
|
||||
%li
|
||||
%code Added
|
||||
per le nuove funzionalità.
|
||||
%li
|
||||
%code Changed
|
||||
per le modifiche a funzionalità esistenti.
|
||||
%li
|
||||
%code Deprecated
|
||||
per le funzionalità che saranno rimosse nelle release future.
|
||||
%li
|
||||
%code Removed
|
||||
per funzionalità deprecate rimosse in questa release.
|
||||
%li
|
||||
%code Fixed
|
||||
per tutti i bug fix.
|
||||
%li
|
||||
%code Security
|
||||
per invitare gli utilizzatori ad aggiornare in caso di vulnerabilità.
|
||||
|
||||
.effort
|
||||
|
||||
%h3#effort
|
||||
%a.anchor{ href: "#effort", aria_hidden: "true" }
|
||||
How can I reduce the effort required to maintain a changelog?
|
||||
|
||||
%p
|
||||
Keep an <code>Unreleased</code> section at the top to track upcoming
|
||||
changes.
|
||||
|
||||
%p This serves two purposes:
|
||||
|
||||
%ul
|
||||
%li
|
||||
People can see what changes they might expect in upcoming releases
|
||||
%li
|
||||
At release time, you can move the <code>Unreleased</code> section
|
||||
changes into a new release version section.
|
||||
|
||||
.bad-practices
|
||||
%h3#bad-practices
|
||||
%a.anchor{ href: "#bad-practices", aria_hidden: "true" }
|
||||
Can changelogs be bad?
|
||||
%p Yes. Here are a few ways they can be less than useful.
|
||||
%h4#log-diffs
|
||||
%a.anchor{ href: "#log-diffs", aria_hidden: "true" }
|
||||
Commit log diffs
|
||||
|
||||
%p
|
||||
Using commit log diffs as changelogs is a bad idea: they're full of
|
||||
noise. Things like merge commits, commits with obscure titles,
|
||||
documentation changes, etc.
|
||||
|
||||
%p
|
||||
The purpose of a commit is to document a step in the evolution of
|
||||
the source code. Some projects clean up commits, some don't.
|
||||
|
||||
%p
|
||||
The purpose of a changelog entry is to document the noteworthy
|
||||
difference, often across multiple commits, to communicate them
|
||||
clearly to end users.
|
||||
|
||||
%h4#ignoring-deprecations
|
||||
%a.anchor{ href: "#ignoring-deprecations", aria_hidden: "true" }
|
||||
Ignoring Deprecations
|
||||
%p
|
||||
When people upgrade from one version to another, it should be
|
||||
painfully clear when something will break. It should be possible to
|
||||
upgrade to a version that lists deprecations, remove what's
|
||||
deprecated, then upgrade to the version where the deprecations
|
||||
become removals.
|
||||
%p
|
||||
If you do nothing else, list deprecations, removals, and any
|
||||
breaking changes in your changelog.
|
||||
%h4#confusing-dates
|
||||
%a.anchor{ href: "#confusing-dates", aria_hidden: "true" }
|
||||
Confusing Dates
|
||||
|
||||
%p
|
||||
In the U.S., people put the month first (<code>06-02-2012</code> for
|
||||
June 2nd, 2012), while many people in the rest of the world write a
|
||||
robotic-looking <code>2 June 2012</code>, yet pronounce it
|
||||
differently. <code>2012-06-02</code> works logically from largest to
|
||||
smallest, doesn't overlap in ambiguous ways with other date formats,
|
||||
and is an #{link_to "ISO standard", iso}. Thus, it is the
|
||||
recommended date format for changelogs.
|
||||
|
||||
%aside
|
||||
There’s more. Help me collect these antipatterns by
|
||||
= link_to "opening an issue", issues
|
||||
or a pull request.
|
||||
|
||||
.frequently-asked-questions
|
||||
%h3#frequently-asked-questions
|
||||
%a.anchor{ href: "#frequently-asked-questions", aria_hidden: "true" }
|
||||
Frequently Asked Questions
|
||||
%h4#standard
|
||||
%a.anchor{ href: "#standard", aria_hidden: "true" }
|
||||
Is there a standard changelog format?
|
||||
|
||||
%p
|
||||
Not really. There's the GNU changelog style guide, or the two-
|
||||
paragraph-long GNU NEWS file "guideline". Both are inadequate or
|
||||
insufficient.
|
||||
|
||||
%p
|
||||
This project aims to be
|
||||
= link_to "a better changelog convention.", changelog
|
||||
It comes from observing good practices in the open source
|
||||
community and gathering them.
|
||||
|
||||
%p
|
||||
Healthy criticism, discussion and suggestions for improvements
|
||||
= link_to "are welcome.", issues
|
||||
|
||||
|
||||
%h4#filename
|
||||
%a.anchor{ href: "#filename", aria_hidden: "true" }
|
||||
What should the changelog file be named?
|
||||
|
||||
%p
|
||||
Call it <code>CHANGELOG.md</code>. Some projects use
|
||||
<code>HISTORY</code>, <code>NEWS</code> or <code>RELEASES</code>.
|
||||
|
||||
%p
|
||||
While it's easy to think that the name of your changelog file
|
||||
doesn't matter that much, why make it harder for your end users to
|
||||
consistently find notable changes?
|
||||
|
||||
%h4#github-releases
|
||||
%a.anchor{ href: "#github-releases", aria_hidden: "true" }
|
||||
What about GitHub Releases?
|
||||
%p
|
||||
It's a great initiative. #{link_to "Releases", ghr} can be used to
|
||||
turn simple git tags (for example a tag named <code>v1.0.0</code>)
|
||||
into rich release notes by manually adding release notes or it can
|
||||
pull annotated git tag messages and turn them into notes.
|
||||
%p
|
||||
GitHub Releases create a non-portable changelog that can only be
|
||||
displayed to users within the context of GitHub. It's possible to
|
||||
make them look very much like the Keep a Changelog format, but it
|
||||
tends to be a bit more involved.
|
||||
%p
|
||||
The current version of GitHub releases is also arguably not very
|
||||
discoverable by end-users, unlike the typical uppercase files
|
||||
(<code>README</code>, <code>CONTRIBUTING</code>, etc.). Another
|
||||
minor issue is that the interface doesn't currently offer links to
|
||||
commit logs between each release.
|
||||
%h4#automatic
|
||||
%a.anchor{ href: "#automatic", aria_hidden: "true" }
|
||||
Can changelogs be automatically parsed?
|
||||
|
||||
%p
|
||||
It’s difficult, because people follow wildly different formats and
|
||||
file names.
|
||||
|
||||
%p
|
||||
#{link_to "Vandamme", vandamme} is a Ruby gem created by the
|
||||
#{link_to "Gemnasium", gemnasium} team and which parses many (but
|
||||
not all) open source project changelogs.
|
||||
|
||||
|
||||
%h4#yanked
|
||||
%a.anchor{ href: "#yanked", aria_hidden: "true" }
|
||||
What about yanked releases?
|
||||
|
||||
%p
|
||||
Yanked releases are versions that had to be pulled because of a
|
||||
serious bug or security issue. Often these versions don't even
|
||||
appear in change logs. They should. This is how you should display
|
||||
them:
|
||||
|
||||
%p <code>## 0.0.5 - 2014-12-13 [YANKED]</code>
|
||||
|
||||
%p
|
||||
The <code>[YANKED]</code> tag is loud for a reason. It's important
|
||||
for people to notice it. Since it's surrounded by brackets it's also
|
||||
easier to parse programmatically.
|
||||
|
||||
|
||||
%h4#rewrite
|
||||
%a.anchor{ href: "#rewrite", aria_hidden: "true" }
|
||||
Should you ever rewrite a changelog?
|
||||
|
||||
%p
|
||||
Sure. There are always good reasons to improve a changelog. I
|
||||
regularly open pull requests to add missing releases to open source
|
||||
projects with unmaintained changelogs.
|
||||
|
||||
%p
|
||||
It's also possible you may discover that you forgot to address a
|
||||
breaking change in the notes for a version. It's obviously important
|
||||
for you to update your changelog in this case.
|
||||
|
||||
|
||||
%h4#contribute
|
||||
%a.anchor{ href: "#contribute", aria_hidden: "true" }
|
||||
How can I contribute?
|
||||
|
||||
%p
|
||||
This document is not the <strong>truth</strong>; it’s my carefully
|
||||
considered opinion, along with information and examples I gathered.
|
||||
|
||||
%p
|
||||
This is because I want our community to reach a consensus. I believe
|
||||
the discussion is as important as the end result.
|
||||
|
||||
%p
|
||||
So please <strong>#{link_to "pitch in", gh}</strong>.
|
||||
|
||||
.press
|
||||
%h3 Conversations
|
||||
%p
|
||||
I went on #{link_to "The Changelog podcast", thechangelog}
|
||||
to talk about why maintainers and contributors should care about changelogs,
|
||||
and also about the motivations behind this project.
|
||||
Contact GitHub API Training Shop Blog About
|
||||
© 2017 GitHub, Inc. Terms Privacy Security Status Help
|
||||
Loading…
x
Reference in New Issue
Block a user