On May 3, 2013, at 9:33 PM, Anomie wrote:
On Fri, May 3, 2013 at 1:02 PM, Krinkle 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.
I believe that a (filtered) list of good summaries is indeed sufficient for the release
notes. The projects I referenced as example already proof this fact. I don't think it
is realistic to think that we need a different type of message for the release notes for
each change.
There are some changes (by far not the majority) that require special attention, for
example when:
* the site admin needs to make changes to their configuration prior or during upgrading
* the site admin needs to update specific extensions at the same time due to breaking
compatibility
* an extension maintainer should make changes soon due to deprecation of a feature
* an extension maintainer needs to ensure changes are made due to removal of a feature
* etc.
However in such case an entry in the list of changes in the release notes that is more
elaborate than the others doesn't really stand out. In such case, as I believe we have
in most cases already, the text in question needs to be written in a paragraph in the
Compatibility, Upgrading or similar sections.
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/
Though this is not a typical type of change and I think you already
know the answer, I'll give you my take on this one.
As commit subject (and thus release notes change log entry) I'd use:
"Add hook LanguageLinks for changing langlinks before display"
Regarding the change itself:
1) I think this hook should be renamed as it ambiguous. It could be a
hook for changing langlinks when parsing/saving a page (input) or a
hook to implement a custom source of langlinks when requesting them
(output).
2) I'm not sure why you'd make ApiParse not call the hook by default.
An option to get the raw langlinks may be useful (I'd be curious as to
the use cases, but I can imagine), but doing so by default seems odd.
Regarding the release notes:
This change is a typical case where extra-awareness notes are in
order. I personally wouldn't consider these breaking changes, but
anyway, they are certainly important. So these are are the kind of
changes for which you'd include notes in a separate section.
Which brings me to another point.
No doubt these are breaking changes, but in a way almost every change
is potentially a breaking change for something for someone,
somewhere.
The kind of changes that break things we previously supported should
be noted in those separate sections. Thus resulting in a situation
where the change log is skimmable for the curious and only containing
summaries of notable changes. And anything that requires attention is
clearly separate and to be read first for all eyes (breaking changes
for site admins or extension maintainers and configuration changes).
-- Krinkle