On 03/14/2018 12:05 PM, Aravinda wrote: > On 03/14/2018 05:38 PM, Shyam Ranganathan wrote: >> On 03/14/2018 02:40 AM, Aravinda wrote: >>> I have following suggestion for managing release notes. Let me know >>> if this can be included in automation document. >> Aravinda, I assume this is an additional suggestion, orthogonal to the >> current discussion around spec and docs, right? > Yes. Sorry about that.
No worries, setting the context was important (to me). >> >>> >>> If a Github issue used in Commit message as "Fixes: #<id>" then Smoke >>> test should fail if patch does not contain >>> `$SRC/release-notes/<issue>.md` >>> (if `$SRC/release-notes/<issue>.md` not already exists in codebase) >>> >>> On branching, delete all these release-notes from Master branch and >>> start >>> fresh. Release branch now contains these notes for all the features >>> went in after the last release. Release manager's job is to merge all >>> these release notes into single release notes document. >>> >>> We can restrict on the format of release-note as, >>> >>> First Line is Title >>> Tags: component-name, keywords etc >>> -- >>> Description about the feature, example, links etc >>> >>> If all patches are submitted with `Updates` instead of `Fixes`, then >>> Issue can't be closed without submitting patch with release-note. >> Most of the above is fine and we can thrash out specifics, but... >> >> I am thinking differently, if spec and doc are provided writing a short >> 1-5 line summary in the release notes is not a problem. > > I think developer who developed the feature is the best person to write > the release notes. Release notes are easy to write while developing the > feature or just after finishing the feature. Once developer starts working > on other features/bug fixes it is very difficult to get interest in writing > release-note for an already merged feature. > > I think extracting summary from the documentation is also difficult, if the > release maintainer not aware of all the features then it will be more > time-consuming to write summary. I agree to a lot of the points, if the author provided the required release note it would be perfect (edits for style and other such will still happen, but are far less technical in nature). I am all for a bot that reminds folks that release notes are pending and hence cannot merge the code. The nature of implementing this, a separate release-notes.md file update in the commit, or a separate section in the design document/text is something we can debate about. We are instating a process of requiring the design doc and getting a "DocApproved" flag. Now, this doc and its approval flag can be granted once appropriate release notes are also present, that way we have one place to do this and one flag to worry about, thoughts? > >> >> The issue at present is that, to get contents into the release notes, at >> times even the code has to be read to understand options, defaults and >> what not. This being done by one person has been a challenge. >> >> So if we address spec and doc, I/we can check how easy it is to write >> release notes from these (over the next couple of releases say) and then >> decide if we want authors to provide the release notes as well. >> >> Thoughts? >> >> Shyam > > _______________________________________________ Gluster-devel mailing list Gluster-devel@gluster.org http://lists.gluster.org/mailman/listinfo/gluster-devel
