Ho letto sulla versione semantica.
Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation.
Quindi, i doccomments sopra i metodi pubblici della mia biblioteca conta come una dichiarazione di API pubblica?
class FooBar
{
/**
* Does this and that and this
* @param array $list
* @return boolean
*/
public function doSomething($list) ....
}
Per versioning semantico , non importa se tale commento è visto come parte dell'API pubblica o no. Ciò che conta è che una modifica al commento significa ai numeri di versione.
Citando le regole principali per i numeri di versione dal precedente link:
Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
Quindi, quando cambi il commento nel tuo codice e nient'altro e prevedi di ripubblicare la tua lib, la domanda è quale delle 3 parti del numero di versione deve essere incrementata?
In primo luogo, tale modifica non è quasi mai una modifica API incompatibile, dal momento che non è stato modificato nulla nel comportamento della libreria: nessun codice funzionante basato su tale libreria verrà effettivamente interrotto. Quindi, non è necessario incrementare la parte MAJOR (vedere il commento di @ JörgWMittag per le eccezioni da questo caso).
In secondo luogo, se il commento ora menziona una funzionalità dell'API che era precedentemente non documentata (e non ovvia dalle firme o dal contesto), allora la modifica del commento rende disponibile agli utenti una nuova funzionalità, ma in un retrocompatibile maniera. Ciò potrebbe giustificare un aumento della parte MINOR. Inoltre, quando aggiungi una nota "deprecata" al commento di una funzione, la regola # 7 di SemVer indica chiaramente, MINOR deve essere aumentato.
Se il commento è solo un miglioramento della descrizione o corregge qualcosa che è stato documentato in modo errato, quindi aumenta il numero PATCH.
Leggi altre domande sui tag semantic-versioning