GSoC 17: Release notes extension

Gregory Szorc gregory.szorc at gmail.com
Fri Mar 24 00:14:35 EDT 2017


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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.mercurial-scm.org/pipermail/mercurial-devel/attachments/20170323/e4c245d0/attachment.html>


More information about the Mercurial-devel mailing list