diff --git a/source/it-IT/index.haml b/source/it-IT/index.haml new file mode 100644 index 0000000..c1e3dc3 --- /dev/null +++ b/source/it-IT/index.haml @@ -0,0 +1,178 @@ +--- +description: Keep a Changelog +title: Keep a Changelog +language: it +--- + +:markdown + # Mantenere un CHANGELOG + + ## Non lasciate che i vostri amici copino e incollino i git log nei CHANGELOG ™ + + ### Cos'è un change log? + Un change log è un file che contiene una lista curata e ordinata cronologicamente delle modifiche degne di nota per ogni versione di un progetto. + +%pre.changelog= File.read(File.expand_path("../../CHANGELOG.md", __FILE__)) + +:markdown + ### A cosa serve un change log? + Per rendere facile agli utilizzatori e contributors vedere con precisione quali modifiche + importanti sono state fatte tra ogni release (o versione) del progetto + + ### Why should I care? + Because software tools are for people. If you don’t care, why are + you contributing to open source? Surely, there must be a kernel (ha!) + of care somewhere in that lovely little brain of yours. + + I [talked with Adam Stacoviak and Jerod Santo on The Changelog][thechangelog] + (fitting, right?) podcast about why maintainers and + contributors should care, and the motivations behind this project. + If you can spare the time (1:06), it’s a good listen. + + ### What makes a good change log? + I’m glad you asked. + + Un buon change log si attiene ai seguenti principi: + + - It’s made for humans, not machines, so legibility is crucial. + - Easy to link to any section (hence Markdown over plain text). + - Una sotto-sezione per ogni versione. + - Elenca le release in ordine cronologico inverso (quelle più recenti all'inizio). + - Scrive tutte le date nel formato `YYYY-MM-DD`. (Esempio: `2012-06-02` sta per `2 Giugno 2012`). è internazionale, [sensible](http://xkcd.com/1179/), e indipendente dalla lingua. + - Explicitly mention whether the project follows [Semantic Versioning][semver]. + - Ogni versione dovrebbe: + - Elencare la sua data di rilascio nel formato specificato sopra. + - Group changes to describe their impact on the project, as follows: + - `Added` for new features. + - `Changed` for changes in existing functionality. + - `Deprecated` for once-stable features removed in upcoming releases. + - `Removed` for deprecated features removed in this release. + - `Fixed` for any bug fixes. + - `Security` to invite users to upgrade in case of vulnerabilities. + + ### Come posso minimizzare lo sforzo richiesto? + Usa sempre una sezione `"Unreleased"` all'inizio per tenere traccia di qualsiasi modifica. + + Questo serve per due scopi: + + - People can see what changes they might expect in upcoming releases + - At release time, you just have to change `"Unreleased"` to the version number + and add a new `"Unreleased"` header at the top. + + ### What makes unicorns cry? + Alright…let’s get into it. + + - **Dumping a diff of commit logs.** Just don’t do that, you’re helping nobody. + - **Not emphasizing deprecations.** When people upgrade from one version to + another, it should be painfully clear when something will break. + - **Dates in region-specific formats.** In the U.S., people put the month first + ("06-02-2012" for June 2nd, 2012, which makes *no* sense), while many people + in the rest of the world write a robotic-looking "2 June 2012", yet pronounce + it differently. "2012-06-02" works logically from largest to smallest, doesn't + overlap in ambiguous ways with other date formats, and is an + [ISO standard](http://www.iso.org/iso/home/standards/iso8601.htm). Thus, it + is the recommended date format for change logs. + + There’s more. Help me collect those unicorn tears by + [opening an issue][issues] + or a pull request. + + ### Is there a standard change log format? + Sadly, no. Calm down. I know you're furiously rushing to find that link + to the GNU change log style guide, or the two-paragraph GNU NEWS file + "guideline". The GNU style guide is a nice start but it is sadly naive. + There's nothing wrong with being naive but when people need + guidance it's rarely very helpful. Especially when there are many + situations and edge cases to deal with. + + This project [contains what I hope will become a better CHANGELOG file convention][CHANGELOG]. + I don't think the status quo is good enough, and I think that as a community we + can come up with better conventions if we try to extract good practices from + real software projects. Please take a look around and remember that + [discussions and suggestions for improvements are welcome][issues]! + + ### What should the change log file be named? + Well, if you can’t tell from the example above, `CHANGELOG.md` is the + best convention so far. + + Some projects also use `HISTORY.txt`, `HISTORY.md`, `History.md`, `NEWS.txt`, + `NEWS.md`, `News.txt`, `RELEASES.txt`, `RELEASE.md`, `releases.md`, etc. + + It’s a mess. All these names only makes it harder for people to find it. + + ### Why can’t people just use a `git log` diff? + Because log diffs are full of noise — by nature. They could not make a suitable + change log even in a hypothetical project run by perfect humans who never make + typos, never forget to commit new files, never miss any part of a refactoring. + The purpose of a commit is to document one atomic step in the process by which + the code evolves from one state to another. The purpose of a change log is to + document the noteworthy differences between these states. + + As is the difference between good comments and the code itself, + so is the difference between a change log and the commit log: + one describes the *why*, the other the how. + + ### Can change logs be automatically parsed? + It’s difficult, because people follow wildly different formats and file names. + + [Vandamme][vandamme] is a Ruby gem + created by the [Gemnasium][gemnasium] team and which parses + many (but not all) open source project change logs. + + ### Why do you alternate between spelling it "CHANGELOG" and "change log"? + "CHANGELOG" is the name of the file itself. It's a bit shouty but it's a + historical convention followed by many open source projects. Other + examples of similar files include [`README`][README], [`LICENSE`][LICENSE], + and [`CONTRIBUTING`][CONTRIBUTING]. + + The uppercase naming (which in old operating systems made these files stick + to the top) is used to draw attention to them. Since they're important + metadata about the project, they could be useful to anyone intending to use + or contribute to it, much like [open source project badges][shields]. + + When I refer to a "change log", I'm talking about the function of this + file: to log changes. + + ### What about yanked releases? + 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: + + `## 0.0.5 - 2014-12-13 [YANKED]` + + The `[YANKED]` 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. + + ### Should you ever rewrite a change log? + Sure. There are always good reasons to improve a change log. I regularly open + pull requests to add missing releases to open source projects with unmaintained + change logs. + + 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 + change log in this case. + + ### Come posso contribuire? + Questo documento non e' la **verità**; it’s my carefully considered + opinion, along with information and examples I gathered. + Although I provide an actual [CHANGELOG][] on [the GitHub repo][gh], + I have purposefully not created a proper *release* or clear list of rules + to follow (as [SemVer.org][semver] does, for instance). + + This is because I want our community to reach a consensus. I believe the + discussion is as important as the end result. + + So please [**pitch in**][gh]. + + [CHANGELOG]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md + [CONTRIBUTING]: https://github.com/olivierlacan/keep-a-changelog/blob/master/CONTRIBUTING.md + [LICENSE]: https://github.com/olivierlacan/keep-a-changelog/blob/master/LICENSE + [README]: https://github.com/olivierlacan/keep-a-changelog/blob/master/README.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/