Puoi consigliare un buon modello di note sulla versione? [chiuso]

7

Sto cercando un buon modello di note sulla versione. Forse in un semplice testo o in un modulo HTML. Cosa usi?

Modifica Ho dimenticato di menzionare che queste note verranno utilizzate internamente nella nostra azienda per altri sviluppatori che utilizzano le nostre librerie.

Sono interessato a ciò in cui credi che una nota di rilascio dovrebbe e non dovrebbe contenere. Per esempio. elenchate tutti i problemi aperti o solo i problemi chiusi in questa versione? Mantenete tutte le note di rilascio precedenti nello stesso file (possibilmente in ordine cronologico invertito) oppure avete documenti separati per ogni versione?

Un paio di esempi che ho trovato sul sito web di Apache:

posta Stefano Ricciardi 08.04.2011 - 11:52
fonte

1 risposta

3

Potrebbe anche dipendere da cosa sei costruito e come. I nostri artefatti sono principalmente in Java e il nostro sistema di compilazione è Maven, quindi utilizziamo il sito generato da Maven per documentare i dettagli degli artefatti. Parlando in particolare delle note di rilascio, c'è il maven-changes-plugin che genera un bel report HTML con descrizioni di ciò che è cambiato e link ai nostri bug bugzilla, da un file xml gestito che conserviamo con ogni progetto. Credo che abbia la possibilità di generare automaticamente tali informazioni anche da JIRA (ma non lo usiamo). Altri plug-in generano report sulla copertura del codice, versioni di dipendenze, risultati di analisi statiche, creando un bel pacchetto accurato da vedere per tutti i nostri sviluppatori interni.

Modifica in risposta alla tua modifica - >

Penso che le note di rilascio rivolte agli sviluppatori dovrebbero contenere tutti i problemi risolti con la versione corrente. Se avessi preso di mira un insieme di note per persone non tecniche (ad esempio un'applicazione finale invece di una libreria), penso che potrebbe contenere solo problemi funzionali di alto livello che sono stati risolti, in quanto non sarebbero necessariamente interessati al tecnico nitty grintoso, proprio quello che tali cambiamenti significherebbe per gli utenti finali. Penso che le note debbano contenere un link al tracker del problema, in modo che le persone possano vedere e cercare i problemi aperti (o nel caso non tecnico, scavare più a fondo in problemi chiusi), ma non penso che i problemi di quotazione aperti nella tua versione le note sono necessarie perché potresti trovare sempre più problemi dopo il rilascio e non vuoi entrare in un ciclo di dover aggiornare le tue note di rilascio precedenti ogni volta. (Se c'è un problema davvero importante, potresti giustificare un aggiornamento, ma come regola generale, non penso che ne valga la pena)

Al momento manteniamo tutte le note di rilascio nello stesso file (per versione, versione corrente in alto), perché è molto più facile per me cercare di determinare quando è stato risolto il problema X, per scorrere una pagina, anziché attraverso diversi pagine. Potrei vedere se le note diventano piuttosto lunghe, potresti interromperlo a un certo punto e collegarti solo alle vecchie note di rilascio, ma ciò avverrebbe dopo diverse serie di versioni. (È vero che utilizziamo i siti Maven, e manteniamo il sito anche per tutte le versioni precedenti, così possiamo dare una sbirciatina anche in questo modo).

    
risposta data 08.04.2011 - 12:28
fonte

Leggi altre domande sui tag