Confusione tra versioni del pacchetto software

0

Sto lavorando nel dominio del software incorporato e la mia area di lavoro principale è lo sviluppo del firmware per vari MCU.

Seguo la struttura delle cartelle come indicato di seguito per qualsiasi progetto firmware per rilasciare il codice sorgente e i documenti come bundle completo (archivio .zip) per l'utilizzo da parte del cliente.

XYZ-project-2.0.zip |-> docs/ |-> XYZ-project-software-design-desciption-rev1.1.pdf |-> XYZ-project-software-user-guide-rev1.3.pdf |-> src/ |-> XYZ-project/ |-> src/ |-> test.c |-> inc/ |-> test.h Il codice sorgente contiene commenti Doxygen. e contiene il numero di versione 2.0 (uguale al file zip). Il cliente fa sempre riferimento a questa versione per qualsiasi discussione.

Quindi, ci sono due cose principali che possono essere modificate indipendentemente. Uno è il codice sorgente e l'altro è documenti.

incremento il numero di versione di XYZ-project-2.0.zip in XYZ-project-2.1.zip quando

  • Se il codice sorgente è cambiato (aggiorno anche il numero di versione nei commenti doxygen da 2.0 a 2.1)
  • Oppure qualsiasi versione del documento è stata modificata.

Il problema:

  • Ogni volta che aggiorno un documento, cambio il numero di versione di quel documento (da XYZ-project-software-user-guide-rev1.3.pdf a XYZ-project-software-user-guide-rev1.4.pdf) e aggiornare il numero di versione del file zip (da XYZ-project-2.0.zip a XYZ-project-2.1.zip). ma devo anche aggiornare il numero di versione nel codice sorgente per mantenerlo uguale (commento della versione di ossigeno da 2.0 a 2.1).

Quindi, La mia domanda è,

  • Esiste uno standard di settore per correlare la versione del software e la versione del documento. E come devo la versione finale del file zip?
  • Dubito ancora di quale tag di versione dovrei aggiungere a qualsiasi documento. doc-Rev1.0.pdf? doc-v1.0.pdf? doc-Ap-A.pdf? C'è qualche standard?

Grazie.

    
posta Jaydeep Dhrangdhariya 22.12.2016 - 15:10
fonte

2 risposte

2

Personalmente, vorrei monitorare le revisioni della documentazione separatamente dal progetto:

  • Document_v1_0_rev_A.pdf
  • Document_v1_0_rev_B.pdf

Cambiando la documentazione non cambia il codice , quindi cambiare il numero di versione del software stesso sembra irragionevole.

Se ho il file zip 2.0 e mi mandi il file 2.1, supporrò che qualcosa sia cambiato di cui ho bisogno di essere a conoscenza. Potrei programmare una serie di test di accettazione o trascorrere qualche ora a leggere la documentazione "what's changed", ecc.

Se hai aggiornato il numero di versione solo perché hai corretto un errore di battitura nella documentazione, sarò molto seccato con te.

Vedi anche Versioning semantico - definizioni specifiche per ciascuno dei 3 o 4 campi normalmente presenti in una stringa di versione.

    
risposta data 22.12.2016 - 15:22
fonte
2

Hai un pacchetto e alcune parti all'interno del pacchetto (codice e documento). Ogni parte del pacchetto può avere un numero di versione da solo e il pacchetto stesso un altro. Chiamiamo quindi questi tre numeri

  • numero di versione del codice (forse da qualche parte all'interno del codice)
  • numero di versione del documento (magari da qualche parte all'interno dei documenti)
  • numero di versione del pacchetto

Quando cambi una delle parti, il pacchetto ottiene il numero di versione aumentato, ma non viceversa . Per combinare questo con il requisito di fare riferimento al numero di versione pacchetto all'interno della documentazione generata da doxygen, devi inserire il numero di versione del pacchetto

  • in un posto (e solo uno)
  • al di fuori del codice e delle parti del documento
  • da qualche parte, in formato leggibile dalla macchina, in cui lo script zippato (lo script che inserisce il numero di versione nel nome del file zip) e doxygen può trovarlo.

Spero che tu abbia l'idea - dovresti provare a creare una unica fonte di verità (quindi evita di mantenere lo stesso numero in due punti come nel nome del pacchetto e i documenti). E dovresti evitare le dipendenze cicliche - poiché il pacchetto di livello superiore dipende dalle parti, evitare di avere una dipendenza diretta dalle parti al nome del pacchetto. Invece, lascia che siano tutti dipendenti dalla fonte separata.

Ad esempio, un semplice file di testo contenente il numero di versione del pacchetto lo farà, da qualche parte nella parte superiore della gerarchia. Forse troverai questo precedente post SO utile come includere tale archiviare in doxygen. Inoltre, sarà probabilmente una buona idea, ogni volta che si fa riferimento a un numero di versione all'interno del doxygen doc, chiarire se è il numero di versione del codice o il numero di versione del pacchetto che si intende.

Il formato esatto della versione e dei numeri di revisione dipende da te, Dan Pichelman ha già menzionato il versioning semantico, che è un approccio ragionevole per scegliere i numeri, ma non l'unico possibile o solo corretto.

    
risposta data 22.12.2016 - 16:00
fonte