On Fri, May 3, 2013 at 1:02 PM, Krinkle <krinklemail(a)gmail.com> wrote:
First of all, I think a lot of our commit subjects are
poorly written,
even for a commit message. Having said that, a good commit subject is
also a good release note (that is, if the change itself is notable for
release notes). I don't think that these extensive paragraphs of text
we are known for in release notes are a good habit.
In my opinion, a good commit summary and a good release note are not
necessarily the same thing at all, otherwise we could just dump the
git log as the release notes and be done with it. Release notes
*should* go into sufficient detail to tell the reader what it is they
should be noting.
We already have a 62-char limit for the commit
subject. That seems to
be going well. Assuming that we properly summarise changes that way
already, why would one need more room in the release notes? It is the
same event.
Taking a recent example,[1] please tell me how to compress the
following into 62 characters:
(in the New features section)
* (bug 45535) introduced the new 'LanguageLinks' hook for manipulating the
language links associated with a page before display.
(in the API section)
* BREAKING CHANGE: action=parse no longer returns all langlinks for the page
with prop=langlinks by default. The new effectivelanglinks parameter will
request that the LanguageLinks hook be called to determine the effective
language links.
* BREAKING CHANGE: list=allpages, list=langbacklinks, and prop=langlinks do not
apply the new LanguageLinks hook, and thus only consider language links
stored in the database.
I don't think "Add LanguageLinks hook with breaking changes to 4 API
modules" is detailed enough for release notes. And before you try to
cheat and split it into multiple commits, note that the new hook and
what it means for how langlinks are stored in the database is what is
the breaking change in those API modules; the actual changes to the
API modules are just mitigating or noting it.
The summary actually used for that revision, BTW, was "(bug 45535)
Hook for changing language links".
[1]:
https://gerrit.wikimedia.org/r/#/c/59997/
"If you don't know what you're doing,
don't do it?"
But do you know that you don't know?
--
Brad Jorsch
Software Engineer
Wikimedia Foundation