Come annunciare modifiche incompatibili con le versioni precedenti nel progetto OSS?

Question

A volte è necessario introdurre modifiche incompatibili con le versioni precedenti, quando i miglioramenti superano di gran lunga gli svantaggi.È possibile passare facilmente al vecchio comportamento, ma l'utente deve essere consapevole di tali cambiamenti.

Pertanto la domanda è: come annunciare future modifiche incompatibili con le versioni precedenti al progetto FLOSS (open source)., in modo che gli utenti possano prepararsi e modificarne l'utilizzo o configurare il programma in modo che utilizzi il vecchio comportamento.

Poiché si tratta di un progetto OSS, viene confezionato da varie distribuzioni in modo indipendente e potrebbe essere aggiornato automaticamente senza l'intervento dell'utente.E quindi una modifica incompatibile con le versioni precedenti potrebbe compromettere il flusso di lavoro di qualcuno (ad esempio script di terze parti).

Viali attualmente considerati (e utilizzati):

• mailing list del progetto
• home page del progetto
• note di rilascio (primo avviso, poi annuncio)
• blog del manutentore

Modifica 1: Questo cambiamento (incompatibile con le versioni precedenti) potrebbe verificarsi in alcuni maggiore pubblicazione.

Tutte le modifiche riguardano l'aggiunta di protezioni (rifiuto di comandi che possono confondere completamente gli utenti inesperti) o la modifica delle impostazioni predefinite su valori più sensati.

Modifica 2: Nel periodo di transizione viene modificata la configurazione predefinita (che dovrebbe essere modificata in Rifiuta/Nega predefinita). avvisare, con la descrizione di come disattivare un avviso, che proteggerebbe anche da modifiche incompatibili con le versioni precedenti del comportamento predefinito.

Ma se si tratta di un sistema automatizzato che potrebbe non essere d'aiuto...

---

Il progetto in questione è Idiota, sistema di controllo della versione distribuito;
Vedere Dare un preavviso agli utenti A il diario di Gister (Blog di Junio ​​C Hamano)

Answer 1

• Cambia la major del numero di versione
• Annuncialo attraverso tutte le vie a tua disposizione
• Aggiungi un annuncio prominente nel file Leggimi
• Aggiungi codice che converte tra il vecchio e il nuovo se sono necessarie DB o altre modifiche
• Aggiungi codice che rileva l'uso di metodi obsoleti, archiviazione di dati, ecc. e avvisa l'utente prima di eseguire modifiche distruttive
• Poni domande pertinenti di tipo FAQ sui principali siti Web di domande e risposte, così quando le persone hanno domande la risposta è immediata e ovvia utilizzando una semplice ricerca

Ma il numero di versione principale è l'obiettivo primario: le persone si aspettano che le transizioni da 1.x a 2.x causino problemi e fanno più attenzione durante l'aggiornamento.

-Adamo

Answer 2

Hai buone risposte su come spargere la voce.Ma migrare la mia mentalità è il problema più grande per me, soprattutto quando le funzioni deprecate sono nella mia memoria muscolare.Disimparare è più difficile che imparare.

Ricevere avvisi di prossime incompatibilità quando sto effettivamente utilizzando i comandi che cambieranno è particolarmente utile, soprattutto con le modifiche alle impostazioni predefinite.Qualcosa di simile a:

 $ git foo  
 Note: git foo currently defaults to HEAD. Starting with
 version 2.0, git foo will instead default to master.

Answer 3

Potrei scegliere RSS (se esiste), Twitter (se esiste), mailing list (e-mail almeno 3 volte mentre l'aggiornamento si avvicina), homepage (renderla molto contrastante, quindi è facile da vedere) e blog, ovviamente .le note di rilascio vengono lette raramente, quindi considerale come l'ultimo punto di informazione.

(L'ho postato come prima risposta, ma non è apparso)

Answer 4

Tutto quanto sopra in più.

Se hai una modifica dove:

La sintassi esatta di un comando non distruttivo cambierebbe in un comando distruttivo

Non vedo altra opzione se non quella di apportare la modifica Di più dirompente per rendere il vecchio comando completamente non valido in modo che se un utente aggiorna e tenta (o molto probabilmente uno script tenta) il comando vecchio stile termina con un messaggio di errore descrittivo su stderr.Anche usare stderr per messaggi di avviso su comandi con modifiche sottili (o meno sottili) che non sono distruttive è una buona idea.La definizione di distruttivo è un po' più complessa su un repository di origine

Usare gli avvisi stderr per semplici metodi di deprecazione è spesso positivo, ma alcune persone si lamenteranno che rompe i loro script (scritti male).In questi casi un rilascio di deprecazione silenziosa (tutte le forme di deprecazione non invasive) seguito da un rilascio verbale (avvisi stderr) seguito forse (vedi sotto) da un rilascio non funzionale ma presente seguito quindi dalla rimozione totale.Quest'ultima versione non funzionante dipenderà fortemente dal progetto in questione in quanto potrebbe causare più problemi di quanto valga la pena, soprattutto per quegli utenti che si comportano bene e si tengono aggiornati sulle funzionalità deprecate.

Dato che la modifica specifica a cui fai riferimento è la rimozione dei built-in, questo dovrebbe andare bene, probabilmente non avrei fatto un rilascio con i built-in in modalità non funzionale, ma non conosco il progetto abbastanza bene per dirlo con certezza .

Nota per codice piuttosto che modifiche a livello di script, in molti linguaggi moderni è possibile lasciare stub di metodo con attributi/annotazioni che li nasconderanno completamente da IntelliSense e si rifiuteranno di compilare contro di essi.Ciò rende la loro presenza (con una semplice eccezione se utilizzata) un modo molto più carino per scoprire che non puoi usarli rispetto a una MissingMethodException runtime o altro.

Answer 5

Solo i miei $ 0,02.Gli ambienti di sviluppo moderni (in particolare .NET) forniscono mezzi per segnalare allo sviluppatore che determinate API sono dichiarate obsolete/deprecate e verranno rimosse nelle versioni future.Il compilatore Microsoft C/C++ ha #pragma deprecato.

Se nulla di tutto ciò è supportato nel tuo ambiente, fai affidamento su controllo delle versioni per fornire feedback sulla compatibilità.