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).