Ține un jurnal de modificări

Nu-ți lăsa prietenii să arunce jurnalele git în jurnalul de modificări.

Versiune 1.1.0 
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- v1.1 Brazilian Portuguese translation.
- v1.1 German Translation
- v1.1 Spanish translation.
- v1.1 Italian translation.
- v1.1 Polish translation.
- v1.1 Ukrainian translation.

### Changed

- Use frontmatter title & description in each language version template
- Replace broken OpenGraph image with an appropriately-sized Keep a Changelog 
  image that will render properly (although in English for all languages)
- Fix OpenGraph title & description for all languages so the title and 
description when links are shared are language-appropriate

### Removed

- Trademark sign previously shown after the project description in version 
0.3.0

## [1.1.1] - 2023-03-05

### Added

- Arabic translation (#444).
- v1.1 French translation.
- v1.1 Dutch translation (#371).
- v1.1 Russian translation (#410).
- v1.1 Japanese translation (#363).
- v1.1 Norwegian Bokmål translation (#383).
- v1.1 "Inconsistent Changes" Turkish translation (#347).
- Default to most recent versions available for each languages.
- Display count of available translations (26 to date!).
- Centralize all links into `/data/links.json` so they can be updated easily.

### Fixed

- Improve French translation (#377).
- Improve id-ID translation (#416).
- Improve Persian translation (#457).
- Improve Russian translation (#408).
- Improve Swedish title (#419).
- Improve zh-CN translation (#359).
- Improve French translation (#357).
- Improve zh-TW translation (#360, #355).
- Improve Spanish (es-ES) transltion (#362).
- Foldout menu in Dutch translation (#371).
- Missing periods at the end of each change (#451).
- Fix missing logo in 1.1 pages.
- Display notice when translation isn't for most recent version.
- Various broken links, page versions, and indentations.

### Changed

- Upgrade dependencies: Ruby 3.2.1, Middleman, etc.

### Removed

- Unused normalize.css file.
- Identical links assigned in each translation file.
- Duplicate index file for the english version.

## [1.1.0] - 2019-02-15

### Added

- Danish translation (#297).
- Georgian translation from (#337).
- Changelog inconsistency section in Bad Practices.

### Fixed

- Italian translation (#332).
- Indonesian translation (#336).

## [1.0.0] - 2017-06-20

### Added

- New visual identity by [@tylerfortune8](https://github.com/tylerfortune8).
- Version navigation.
- Links to latest released version in previous versions.
- "Why keep a changelog?" section.
- "Who needs a changelog?" section.
- "How do I make a changelog?" section.
- "Frequently Asked Questions" section.
- New "Guiding Principles" sub-section to "How do I make a changelog?".
- Simplified and Traditional Chinese translations from [@tianshuo](https://github.com/tianshuo).
- German translation from [@mpbzh](https://github.com/mpbzh) & [@Art4](https://github.com/Art4).
- Italian translation from [@azkidenz](https://github.com/azkidenz).
- Swedish translation from [@magol](https://github.com/magol).
- Turkish translation from [@emreerkan](https://github.com/emreerkan).
- French translation from [@zapashcanon](https://github.com/zapashcanon).
- Brazilian Portuguese translation from [@Webysther](https://github.com/Webysther).
- Polish translation from [@amielucha](https://github.com/amielucha) & [@m-aciek](https://github.com/m-aciek).
- Russian translation from [@aishek](https://github.com/aishek).
- Czech translation from [@h4vry](https://github.com/h4vry).
- Slovak translation from [@jkostolansky](https://github.com/jkostolansky).
- Korean translation from [@pierceh89](https://github.com/pierceh89).
- Croatian translation from [@porx](https://github.com/porx).
- Persian translation from [@Hameds](https://github.com/Hameds).
- Ukrainian translation from [@osadchyi-s](https://github.com/osadchyi-s).

### Changed

- Start using "changelog" over "change log" since it's the common usage.
- Start versioning based on the current English version at 0.3.0 to help
  translation authors keep things up-to-date.
- Rewrite "What makes unicorns cry?" section.
- Rewrite "Ignoring Deprecations" sub-section to clarify the ideal
  scenario.
- Improve "Commit log diffs" sub-section to further argument against
  them.
- Merge "Why can’t people just use a git log diff?" with "Commit log
  diffs".
- Fix typos in Simplified Chinese and Traditional Chinese translations.
- Fix typos in Brazilian Portuguese translation.
- Fix typos in Turkish translation.
- Fix typos in Czech translation.
- Fix typos in Swedish translation.
- Improve phrasing in French translation.
- Fix phrasing and spelling in German translation.

### Removed

- Section about "changelog" vs "CHANGELOG".

## [0.3.0] - 2015-12-03

### Added

- RU translation from [@aishek](https://github.com/aishek).
- pt-BR translation from [@tallesl](https://github.com/tallesl).
- es-ES translation from [@ZeliosAriex](https://github.com/ZeliosAriex).

## [0.2.0] - 2015-10-06

### Changed

- Remove exclusionary mentions of "open source" since this project can
  benefit both "open" and "closed" source projects equally.

## [0.1.0] - 2015-10-06

### Added

- Answer "Should you ever rewrite a change log?".

### Changed

- Improve argument against commit logs.
- Start following [SemVer](https://semver.org) properly.

## [0.0.8] - 2015-02-17

### Changed

- Update year to match in every README example.
- Reluctantly stop making fun of Brits only, since most of the world
  writes dates in a strange way.

### Fixed

- Fix typos in recent README changes.
- Update outdated unreleased diff link.

## [0.0.7] - 2015-02-16

### Added

- Link, and make it obvious that date format is ISO 8601.

### Changed

- Clarified the section on "Is there a standard change log format?".

### Fixed

- Fix Markdown links to tag comparison URL with footnote-style links.

## [0.0.6] - 2014-12-12

### Added

- README section on "yanked" releases.

## [0.0.5] - 2014-08-09

### Added

- Markdown links to version tags on release headings.
- Unreleased section to gather unreleased changes and encourage note
  keeping prior to releases.

## [0.0.4] - 2014-08-09

### Added

- Better explanation of the difference between the file ("CHANGELOG")
  and its function "the change log".

### Changed

- Refer to a "change log" instead of a "CHANGELOG" throughout the site
  to differentiate between the file and the purpose of the file — the
  logging of changes.

### Removed

- Remove empty sections from CHANGELOG, they occupy too much space and
  create too much noise in the file. People will have to assume that the
  missing sections were intentionally left out because they contained no
  notable changes.

## [0.0.3] - 2014-08-09

### Added

- "Why should I care?" section mentioning The Changelog podcast.

## [0.0.2] - 2014-07-10

### Added

- Explanation of the recommended reverse chronological release ordering.

## [0.0.1] - 2014-05-31

### Added

- This CHANGELOG file to hopefully serve as an evolving example of a
  standardized open source project CHANGELOG.
- CNAME file to enable GitHub Pages custom domain.
- README now contains answers to common questions about CHANGELOGs.
- Good examples and basic guidelines, including proper date formatting.
- Counter-examples: "What makes unicorns cry?".

[unreleased]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.1...HEAD
[1.1.1]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.1.0...v1.1.1
[1.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v1.0.0...v1.1.0
[1.0.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.3.0...v1.0.0
[0.3.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.2.0...v0.3.0
[0.2.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.8...v0.1.0
[0.0.8]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.7...v0.0.8
[0.0.7]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.6...v0.0.7
[0.0.6]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.5...v0.0.6
[0.0.5]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.4...v0.0.5
[0.0.4]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.3...v0.0.4
[0.0.3]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.2...v0.0.3
[0.0.2]: https://github.com/olivierlacan/keep-a-changelog/compare/v0.0.1...v0.0.2
[0.0.1]: https://github.com/olivierlacan/keep-a-changelog/releases/tag/v0.0.1

Ce este un jurnal de modificări?

Un jurnal de modificări este un fișier care conține o listă organizată, ordonată cronologic de modificări notabile pentru fiecare versiune a unui proiect.

De ce să ții un jurnal de modificări?

Pentru ca utilizatorii și colaboratorii să vadă exact ce modificări notabile au fost făcute între fiecare lansare (sau versiune) a proiectului.

Cine are nevoie de un jurnal de modificări?

Oamenii. Indiferent dacă sunt consumatori sau dezvoltatori, utilizatorii finali ai software-ului sunt ființe umane cărora le pasă de ceea ce este în software. Când software-ul se schimbă, oamenii vor să știe de ce și cum.

Cum fac un jurnal de modificări bun?

Principii îndrumătoare

  • Jurnalele de modificări sunt pentru oameni, nu mașini.
  • Ar trebui să existe o intrare pentru fiecare versiune.
  • Aceleași tipuri de modificări ar trebui grupate.
  • Versiunile și secțiunile ar trebui să poată fi legate.
  • Cea mai recentă versiune este pe primul loc.
  • Este afișată data de lansare a fiecărei versiuni.
  • Menționează dacă urmărești Numerotarea Semantică.

Tipuri de modificări

  • Added pentru funcționalități noi.
  • Changed pentru modificări în funcționalitatea existentă.
  • Deprecated pentru funcționalități ce urmează să fie eliminate în curând.
  • Removed pentru funcționalități eliminate acum.
  • Fixed pentru orice erori remediate.
  • Security în caz de vulnerabilități.

Cum pot reduce efortul necesar pentru a menține un jurnal de modificări?

Ține o secțiune Unreleased în partea de sus pentru a urmări modificările viitoare.

Aceasta servește la două scopuri:

  • Oamenii pot vedea la ce schimbări s-ar putea aștepta în lansările viitoare
  • În momentul lansării, poți muta modificările din secțiunea Unreleased într-o nouă secțiune a versiunii de lansare.

Jurnalele de modificări pot fi precare?

Da. Iată câteva moduri în care pot fi mai puțin decât utile.

Comitere jurnal de diferențe

Utilizarea jurnalului de diferențe din comiteri ca jurnal de modificări este o idee proastă: sunt pline de zgomot. Lucruri precum comiterile de îmbinare, comiterile cu titluri obscure, modificările documentației, etc.

Scopul unei comiteri este de a documenta un pas în evoluția codului sursă. Unele proiecte curăță comiterile, altele nu.

Scopul unei intrări din jurnalul de modificări este de a documenta diferența demnă de remarcat, adesea din mai multe comiteri, pentru a le comunica în mod clar utilizatorilor finali.

Ignorarea deprecierilor

Când oamenii fac actualizare de la o versiune la alta, ar trebui să fie foarte clar când ceva nu va funcționa. Ar trebui să fie posibil să actualizezi la o versiune care listează deprecierile, să elimini ceea ce este depreciat, apoi să actualizezi la versiunea în care deprecierile devin eliminări.

Dacă nu faci nimic altceva, enumeră deprecierile, eliminările și orice modificări nerespective în jurnalul tău de modificări.

Date confuze

Formatele regionale de date variază în întreaga lume și este adesea dificil să găsești un format de dată prietenos pentru oameni, care să pară intuitiv pentru toată lumea. Avantajul datelor formatate ca 2017-07-17 este că urmează ordinea de la unitățile mai mari la cele mai mici: an, lună și zi. De asemenea, acest format nu se suprapune în moduri ambigue cu alte formate de dată, spre deosebire de unele formate regionale care schimbă poziția numerelor lunii și zilei. Aceste motive și faptul că acest format de dată este un standard ISO, este motivul pentru care este formatul de dată recomandat pentru intrările din jurnalul de modificări.

Modificări inconsecvente

Un jurnal de modificări care menționează doar unele dintre modificări poate fi la fel de periculos ca și lipsa unui jurnal de modificări. Deși multe dintre modificări pot să nu fie relevante - de exemplu, eliminarea unui singur spațiu alb poate să nu fie nevoie să fie înregistrată în toate cazurile - orice modificări importante ar trebui menționate în jurnalul de modificări. Prin aplicarea inconsecventă a modificărilor, utilizatorii tăi pot crede în mod eronat că jurnalul de modificări este singura sursă de adevăr. Așa ar trebui să fie. Cu o mare putere vine o mare responsabilitate - a avea un jurnal de modificări bun înseamnă a avea un jurnal de modificări actualizat constant.

Întrebări frecvente

Există un format standard de jurnal de modificări?

Nu chiar. Există Ghidul de stil pentru jurnalul de modificări GNU, sau „ghidul” GNU NEWS de două paragrafe Ambele sunt inadecvate sau insuficiente.

Acest proiect își propune să fie o convenție mai bună pentru jurnalul de modificări. El vine din observarea bunelor practici în comunitatea open source și adunarea lor.

Sunt binevenite criticile sănătoase, discuțiile și sugestiile de îmbunătățire.

Cum ar trebui să fie numit fișierul jurnal de modificări?

Numește-l CHANGELOG.md. Unele proiecte folosesc HISTORY, NEWS sau RELEASES.

Deși este ușor de crezut că numele fișierului jurnal de modificări nu contează atât de mult, de ce este mai greu pentru utilizatorii finali să găsească în mod constant modificări notabile?

Ce zici despre Lansările GitHub?

Este o inițiativă grozavă. Lansări poate fi folosit pentru a transforma etichetele git simple (de exemplu, o etichetă numită v1.0.0) în note de lansare bine detaliate, adăugând manual note de lansare sau putând trage mesaje adnotate din etichetele git și transofmându-le în note.

Lansările GitHub creează un jurnal de modificări non-portabil care poate fi afișat numai utilizatorilor în contextul GitHub. Este posibil să le faci să semene foarte mult cu formatul Ține un jurnal de modificări, dar tinde să fie puțin mai implicat.

De asemenea, versiunea actuală a Lansărilor GitHub este probabil puțin descoperită de utilizatorii finali, spre deosebire de fișierele tipice cu majuscule (README, CONTRIBUTING, etc.). O altă problemă minoră este că interfața nu oferă momentan legături pentru a comite jurnale între fiecare lansare.

Jurnalele de modificări pot fi interpretate automat?

Este dificil, pentru că oamenii urmează formate și nume de fișiere extrem de diferite.

Vandamme este un gem Ruby creat de echipa Gemnasium și care interpretează multe (dar nu toate) jurnalele de modificări ale proiectelor open source.

Ce zici despre lansările smulse („yanked”)?

Lansările smulse (de tip „yanked”) sunt versiuni care au trebuit să fie eliminate din cauza unei erori grave sau a unei probleme de securitate. Adesea, aceste versiuni nici măcar nu apar în jurnalele de modificări. Ar trebui. Iată cum ar trebui să le afișezi:

## [0.0.5] - 2014-12-13 [YANKED]

Eticheta [YANKED] este puternică dintr-un motiv. Este important pentru oameni să o observe. Deoarece este înconjurată de paranteze, este, de asemenea, mai ușor de interpretat programatic.

Ar trebui să rescrii vreodată un jurnal de modificări?

Sigur. Există întotdeauna motive bune pentru a îmbunătăți un jurnal de modificări. Eu deschid în mod regulat solicitări de extragere pentru a adăuga versiunile lipsă proiectelor open source cu jurnalele de modificări neîntreținute.

De asemenea, este posibil să descoperi că ai uitat să abordezi o modificare care afectează funcționalitatea în notele pentru o versiune. În mod evident, este important să actualizezi jurnalul de modificări în acest caz.

Cum pot contribui?

Acest document nu este adevărul; este opinia mea atent analizată, împreună cu informațiile și exemplele pe care le-am adunat.

Asta pentru că vreau ca comunitatea noastră să ajungă la un consens. Cred că discuția este la fel de importantă ca și rezultatul final.

Așa că te rog să te prezinți.

Conversații

Am mers la podcastul The Changelog pentru a vorbi despre motivul pentru care întreținătorilor și colaboratorilor ar trebui să le pese de jurnalele de modificări și, de asemenea, despre motivațiile din spatele acestui proiect.