On Sun, Mar 26, 2017 at 10:55 PM, Gregory Szorc <gregory.sz...@gmail.com> wrote:
> On Thu, Mar 23, 2017 at 10:02 PM, Martin von Zweigbergk < > martinv...@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.sz...@gmail.com> >> wrote: >> >>> On Mon, Mar 20, 2017 at 6:04 PM, Rishabh Madan <rishabhmada...@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@mercurial-scm.org >>>> https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel >>>> >>>> >>> >>> _______________________________________________ >>> Mercurial-devel mailing list >>> Mercurial-devel@mercurial-scm.org >>> https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel >>> >>> >> ᐧ
_______________________________________________ Mercurial-devel mailing list Mercurial-devel@mercurial-scm.org https://www.mercurial-scm.org/mailman/listinfo/mercurial-devel