Page MenuHomePhabricator

releasenotes: add a file in which to record release notes
ClosedPublic

Authored by martinvonz on May 2 2019, 12:04 AM.

Details

Summary

I've just spent a few very boring hours going through the changelog
for the 5.0 release (829 commits). We only had 5 commits that used the
syntax that the release notes extension expects. This commit adds a
file in which we can record important changes. The file should
preferably be edited in the patch that makes the important change, but
it can also be edited after (I think this is an important benefit
compared to the release notes extension).

I'm thinking that we can rename the file from "next" to "5.1" or
something when it's time, and then we'd create a new "next" file on
the default branch.

I've used the syntax that we use on the our wiki in the template, but
I don't care much that we use any valid syntax at all. The idea is
mostly to record important changes when they happen. I expect that
some copy editing will be needed at release time anyway.

Diff Detail

Repository
rHG Mercurial
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

martinvonz created this revision.May 2 2019, 12:04 AM

I'd be fine if this was queued as is, but it's mostly just to hear what others think

martinvonz retitled this revision from releasenotes: add a file in which to record release-notes to releasenotes: add a file in which to record release notes.May 2 2019, 12:05 AM
Sietse added a subscriber: Sietse.May 2 2019, 4:26 AM

I think this is a fine idea -- it is more robust, because it does not depend on getting the commit syntax right, but on knowing the right place. It also means commit messages (for developers, one per commit) don't have to do double duty as release notes (for users, one per functional change).

When this patch is accepted, one could make this policy visible by adding an "Update release notes" section to the https://www.mercurial-scm.org/wiki/ContributingChanges checklist.

+1 on the idea of an explcit editable file instead of immutable static entry in the changelog. I would use it.

The main issue emerging from this kind of approach are the conflict in that file. There are multiple way to smooth that out.

martinvonz updated this revision to Diff 15017.May 5 2019, 1:23 AM
pulkit accepted this revision.May 14 2019, 12:40 PM
This revision was automatically updated to reflect the committed changes.