GSoC 17: Release notes extension

[Rishabh Madan]

On Sun, Mar 26, 2017 at 10:55 PM, Gregory Szorc <gregory.szorc at gmail.com>
wrote:

> On Thu, Mar 23, 2017 at 10:02 PM, Martin von Zweigbergk <
> martinvonz at google.com> wrote:
>
>> As an alternative to compiling the release notes from commit messages, we
>> could do what Git does, which is to keep a file per release
>> (Documentation/Relnotes/<version>.txt in their case) that we update
>> every now and then. I think Junio (the maintainer) generally updates that
>> file. We don't have a single maintainer, but we could accept patches to
>> from anyone of course.
>>
>
> Yes, I think having release notes files in the repo is a good idea. If we
> did this, we could start suggesting people update the release notes when
> writing patches.
>
> Of course, there would likely be merge conflicts for whoever queues
> things. There is a "union" merge tool suitable for this case. And there is
> a [merge-patterns] that can be used to specify which tool to use for which
> filenames. But I feel there is a missing feature for a .hgmergepatterns
> file or some such.
>

  I think there is provision for configuring [merge-patterns]. See
https://www.mercurial-scm.org/wiki/MergeToolConfiguration

>
>
>>
>> We could also keep the current process, which is to keep the release
>> notes on the wiki (I just started on https://www.mercurial-scm.org/
>> wiki/Release4.2 yesterday).
>>
>> I did like Greg's extension, but I wonder if it's worth the trouble of
>> having each contributor write part of the release notes. I wonder if we
>> won't want to restructure it enough afterwards anyway that I'm not sure the
>> automated step is worth the trouble. I understand that it helps us not
>> forget to include things in the release notes, but maybe it would be as
>> effective to add a new commit message tag like (RN) in addition to the (BC)
>> and (API) we already have.
>>
>
> This is the path I initially went down. I quickly realized that commit
> message summary lines weren't sufficient for release notes. They are often
> just not appropriate for end users or not detailed enough. This
> necessitates some kind of content elsewhere in the commit to denote release
> notes. This is how the use of ReST admonitions was arrived at.
>
> Regarding restructuring afterwards, my thoughts were the workflow would
> look something like this:
>
> 1. Changeset author adds release notes fragment to commit message
> 2. Person queuing changesets runs `hg releasenotes` to update a release
> notes file in repo
> 3. Later, someone tweaks wording in release notes file
> 4. Subsequent `hg releasenotes` invocations automatically reconcile minor
> differences between commit message and file and give precedence to newer
> content in file.
>

This approach to form release notes seems nice to me.

>
>>
>> On Thu, Mar 23, 2017 at 9:14 PM, Gregory Szorc <gregory.szorc at gmail.com>
>> wrote:
>>
>>> On Mon, Mar 20, 2017 at 6:04 PM, Rishabh Madan <rishabhmadan96 at gmail.com
>>> > wrote:
>>>
>>>> Hello,
>>>>
>>>> I am Rishabh Madan and I will be a GSoC applicant this year under
>>>> Mercurial.
>>>>
>>>> I wanted to discuss about the Release notes extension project.[1]
>>>> <https://www.mercurial-scm.org/wiki/SummerOfCode/Ideas2017>
>>>> I have gone through the mailing list discussions. I am currently
>>>> understanding the intial patch sent by Gregory Szorc, for the releasenotes
>>>> extension.
>>>>
>>>
>>> I hacked on this for an hour or two several days ago. A newer version is
>>> at https://hg.mozilla.org/users/gszorc_mozilla.com/hg/rev/releasenotes.
>>> Not much has fundamentally changed: I was just trying to make commit
>>> message parsing more robust.
>>>
>>>
>>>>
>>>> I would like to get a few inputs for this project:
>>>>
>>>> 1. Commit message parser
>>>> (i) I feel this is the core of the idea. From what I understand, we
>>>> will have to keep a specific format for the commit messages that will be
>>>> parsed and output will be stored in a changelog. But, this is a extension
>>>> that would help other organizations as well. Do we expect them to abide by
>>>> certain format for the commit message?
>>>>
>>>
>>> For this idea to work, you have to standardize on *something*. I chose
>>> to use ReStructured Text admonitions (".. directive:: ...") because a)
>>> Mercurial already has a basic ReST parser and it was easy to leverage ReST
>>> b) ReST is extensible and therefore is a natural fit for this use case.
>>> There's no reason other formats couldn't be leveraged. But for a minimal
>>> viable product, I'd focus on ReST.
>>>
>>> The code as currently written converts extracted release notes fragments
>>> to Python data structures. So it should be possible to plug in other
>>> formats/parsers easily enough.
>>>
>>>
>>>> (ii) Is this going to be a hybrid process? I mean, will the notes once
>>>> created be edited by maintainers at a later stage?
>>>>
>>>
>>> This isn't implemented in my proof-of-concept yet, but yes, we
>>> absolutely need to support edits. The way I envision this being implemented
>>> is that there is some kind of similarity detection to reconcile differences
>>> between release notes fragments in commit messages and release notes files.
>>> Currently, the extension parses commit messages and a release notes file to
>>> a common data structure type, merges/unions the data, and emits a new
>>> release notes file. We need to add a step that attempts to match edited
>>> release notes file entries to their original commit message fragments so
>>> duplicates aren't produced. This can likely utilize the APIs already in
>>> Mercurial for identifying similar content.
>>>
>>>
>>>> (iii) The extension shouldn't add extremely small changesets to the
>>>> changelog. I think this can be done by adding some keyword to the commit
>>>> message (like [IGNORERST]).
>>>>
>>>
>>> As currently implemented, a release notes entry is only produced if the
>>> commit message contains special syntax - a ReST admonition. This avoids the
>>> problem of "extremely small changesets" polluting the release notes. But it
>>> has the drawback of requiring changeset authors to remember to write a
>>> release notes admonition. This trade-off is arguably tailored towards
>>> Mercurial's workflow, which focuses on writing many, smaller changesets
>>> (which results in many changesets being irrelevant to release notes). Since
>>> this extension is being authored to benefit the Mercurial project and since
>>> many of us feel passionately that our "microcommit" approach is superior to
>>> other approaches, we should probably focus on this (as opposed to merely
>>> extracting commit message summary lines to release notes files) :)
>>>
>>>
>>>>
>>>> 2. Linking hgweb to release notes
>>>> I found this idea quite intriguing. Can someone please elaborate a bit
>>>> more on what exactly we're trying to accomplish with this?
>>>>
>>>
>>> I think the idea here is for pages that reference a series or range of
>>> changesets (such as a tag) to automatically extract release notes from
>>> changesets in that range. For example, if you load the "4.2" tag page, you
>>> would have a link to or inline rendering of all release notes relevant to
>>> changesets between 4.1 and 4.2.
>>>
>>> There is a lot of ambiguity in this feature. For example, how do you
>>> handle edits to release notes files? This would require the server to
>>> define where release notes files are stored in the repo. Otherwise, the
>>> hgweb view would only render commit message content, which may not be
>>> complete! For this reason, I think hgweb support should be a secondary goal
>>> of the project.
>>>
>>>
>>>>
>>>> I also found some open source implementations like [2]
>>>> <https://github.com/skywinder/github-changelog-generator> similar to
>>>> this idea that might help in implementing this project.
>>>>
>>>
>>> Yes, there is a lot of prior art in this topic. We can and should look
>>> to others for inspiration for good ideas.
>>>
>>> One thing to keep in mind is that many of these solutions simply
>>> assemble *all* changes. For projects with ~1000 commits every release (like
>>> Mercurial), listing every change is too noisy: you need to curate the
>>> information in release notes or people will get lost in the noise. This is
>>> why the proof-of-concept I've implemented requires explicit opt-in (via a
>>> ReST admonition) to record a release note.
>>>
>>> It is important to note that the thing Mercurial can do with release
>>> notes is integrate them into version control as a fully-supported feature.
>>> Existing solutions rely on leveraging a 3rd party tool. This results in
>>> less adoption and more fragmentation. If your version control tool supports
>>> a well-defined release notes format, it doesn't take much effort to start
>>> writing release notes (it is already supported by your VCS tool!) and the
>>> format is the same across all projects, so you don't need to learn N
>>> variations for writing release notes. This makes writing release notes
>>> easier, which is beneficial for everyone.
>>>
>>>
>>>>
>>>>
>>>> I would really appreciate if someone can point out the issues and
>>>> features I may have missed. Also, any relevant resources or links for
>>>> further readings would help too.
>>>>
>>>
>>> There was also an idea to leverage the feature for "developer
>>> notifications." For example, there could be an ".. alert::" admonition.
>>> When a client `hg pull`s or `hg update`s to a changeset containing this
>>> admonition, it would print the content of that alert. This could be used to
>>> inform people about important changes in the repository. For example,
>>> "alert: the 'foo' tool has been renamed to 'bar.'" This idea isn't as
>>> flushed out, so it isn't a high priority. But at the point you can extract
>>> "news" fragments from commit messages, defining special types that e.g. are
>>> printed during certain operations seems like a nifty and
>>> trivial-to-implement feature!
>>>
>>> Something else not implemented in the current proof-of-concept is the
>>> ability to define your own release notes types. Currently, the ReST
>>> admonitions and titles/sections in the generated release notes files are
>>> statically defined. We almost certainly want these to be customizeable. We
>>> *may* have to use a .hgreleasenotes (or similar) file for this. I haven't
>>> given much thought to this topic yet.
>>>
>>>
>>>>
>>>> Thanks.
>>>> Rishabh Madan
>>>> ᐧ
>>>>
>>>> _______________________________________________
>>>> Mercurial-devel mailing list
>>>> Mercurial-devel at mercurial-scm.org
>>>> https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
>>>>
>>>>
>>>
>>> _______________________________________________
>>> Mercurial-devel mailing list
>>> Mercurial-devel at mercurial-scm.org
>>> https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel
>>>
>>>
>>
ᐧ
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.mercurial-scm.org/pipermail/mercurial-devel/attachments/20170327/016a1c89/attachment.html>