Controllo delle versioni semantiche quando si risolve un bug importante

18

Attualmente gestisco una libreria che ha un elevato utilizzo pubblico e ho avuto una domanda su versioning semantico . Voglio refactoring una parte abbastanza importante della libreria che viene implementata in modo errato - ed è sempre stata implementata in modo errato. Ma fare ciò significherebbe modifiche all'API pubblica, che è una decisione importante.

Il cambiamento che voglio fare ruota attorno a come vengono utilizzati gli iteratori. Attualmente, gli utenti devono fare questo:

while ($element = $iterator->next()) {
   // ...
}

Che non è corretto, almeno nella lingua nativa di PHP Interfaccia Iterator . Voglio sostituire con questo:

while ($iterator->valid()) {
   $element = $iterator->current();
   // ...
   $iterator->next();
}

che è analogo a:

foreach ($iterator as $element) {
    // ...
}

Se si guarda alla guida di Tom alla versione semantica, egli afferma chiaramente che qualsiasi modifica all'API pubblica (cioè quelli che sono non compatibili con le versioni precedenti), dovrebbe giustificare una versione principale. Quindi la libreria passerebbe dalla 1.7.3 alla 2.0.0 che, per me, è un passo troppo lontano. Stiamo solo parlando di una funzione che viene riparata.

Ho in programma di rilasciare alla fine la 2.0.0, ma pensavo che questo fosse quando hai completamente riscritto la libreria e implementato numerose modifiche dell'API pubblica. L'introduzione di questo refactoring giustifica una versione principale della versione? Non riesco davvero a vedere come funziona, mi sento più a mio agio nel rilasciarlo come 1.8.0 o 1.7.4. Qualcuno ha qualche consiglio?

    
posta hohner 28.11.2013 - 14:07
fonte

2 risposte

29

Esiti perché non vuoi creare versioni semantiche, vuoi fare "pubblicità che supporta il controllo delle versioni". Ti aspetti un numero di versione "2.0" per dire al mondo che hai un sacco di nuove fantastiche funzioni nella tua libreria ora, non che hai cambiato l'API. Va bene (molte società di software e / o sviluppatori lo fanno). IMHO hai le seguenti opzioni:

  • mantieni il versioning semantico e convivi con il fatto che devi modificare il numero di versione in 2.0.0
  • cambia il tuo schema di versioning in 4 numeri. "1.1.7.3" è la tua versione ora, "1.2.0.0" la successiva dopo aver cambiato l'API e "2.0.0.0" la prima della "famiglia di prodotti 2.x completamente nuova"
  • rende la tua correzione compatibile all'indietro (quindi non modificare la funzionalità di next , aggiungi solo le funzioni valid e current ). Quindi puoi usare "1.8.0" come numero di versione successivo. Se pensi che cambiare il comportamento di next sia davvero importante, fallo in 2.0.0.
risposta data 28.11.2013 - 14:41
fonte
7

Continua con la guida di Tom alla versione semantica.

Qualsiasi modifica significativa a un'API pubblica deve essere eseguita in uno dei due punti:

  1. Mai
  2. Ad un importante aggiornamento della versione

Il mio voto, a proposito, è per il primo. Ma riconosco che è appropriato solo per cose insignificanti.

Il problema è mantenere la compatibilità con le versioni precedenti e assicurarti di non rompere le cose per gli utenti precedenti della tua API.

In sostanza, stai creando un errore di indicizzazione per gli utenti che non sono a conoscenza della modifica. Forzare un cambiamento come questo costringe tutti i tuoi utenti a fare quanto segue:

  1. Codifica la correzione per utilizzare il nuovo approccio
  2. Convalida la correzione e assicurati che non si sia rotto nulla
  3. Spedisci le nuove versioni dei loro prodotti ai loro utenti finali

Questo può potenzialmente essere un grande sforzo, specialmente se si considera quanto pochi progetti hanno casi di test in atto per convalidare modifiche come questa. La quantità di sforzo si compone quando si considera il numero di utenti a valle dai propri utenti che dovranno anche aggiornare le proprie installazioni.

Per qualcosa di così piccolo, lo lascerei andare e non me ne preoccuperei.
Se ti infastidisce davvero (cosa che apparentemente fa o non avresti chiesto) allora farei quanto segue.

  1. Crea il ramo v2.0.0 nella struttura del codice
  2. Apporta il primo contributo al ramo v2.0.0, che è questa modifica
  3. Invia un'anteprima Release Notes in anticipo sulla trasmissione che il cambiamento sta arrivando

E poi sii paziente poichè ci vorrà un po 'per accumulare altre cose che giustificano l'aggiornamento del numero di versione ad una nuova major release. La notifica avanzata (parte 3) ti dà il tempo di ricevere feedback dagli utenti finali per scoprire quanta parte dell'impatto che cambierà.

Una soluzione alternativa è aggiungere una nuova funzione che operi nel modo desiderato.

Se hai foo() , devi creare fooCorrect() per fornire la correzione ma anche preservare completamente la compatibilità con le versioni precedenti. E ad un certo punto puoi deprecare foo() per far sapere agli altri di non usarlo.

La sfida è che troverai qualcos'altro entro fooCorrect() che richiede il suo aggiornamento e finisci con fooCorrectedCorrect() o qualche altra sciocchezza sciocca.

Se vuoi veramente questo problema ora, questo approccio alternativo è probabilmente il percorso migliore. Essere consapevoli e diffidenti di creare molte funzioni extra in questo modo in quanto rende l'API più difficile da lavorare. E quella consapevolezza potrebbe essere sufficiente per prevenire il peggiore di questi tipi di problemi.

Ma questo potrebbe essere l'approccio "meno male" da considerare per qualcosa di piccolo.

    
risposta data 28.11.2013 - 14:34
fonte

Leggi altre domande sui tag