On May 2, 2013, at 7:41 PM, Brad Jorsch <bjorsch(a)wikimedia.org> wrote:
I like the idea of not having to mess with
RELEASE-NOTES-#.## merge
conflicts. But I'm not entirely sure about everything in the proposal.
On Thu, May 2, 2013 at 12:30 PM, Krinkle <krinklemail(a)gmail.com> wrote:
> To avoid wrong entries for bugs that were
merely mentioned in the commit
> message but not fixed in that commit, it becomes more important that we
> enforce a consistent format. "bug 123" is a mention. "Bug: 123"
in footer
> meta-data indicates the bug was fixed.
So we're changing the semantics of that "Bug" footer already? Instead
of being used for searching changesets related to a bug, now it's only
for searching changesets actually fixing a bug? And what about
changesets that only partially fix a bug? Or bugs where changes to
both core and extensions are needed to fix a bug?
Fair point. We could use some other detectable way instead. However
I'd prefer to keep things simple where "bug 123" is a mention and
"Bug: 123" a resolution. Both are linkified by Gerrit, so that's not
an issue.
We could introduce something like "Bug-Fixed: 123". But I'm not sure
if more syntax is the answer here. Note we also have people using
"(bug 123)" in the subject still, and even people copying BugZilla's
format of "Bug 123: title".
Or we could simply omit this detection altogether and build the list
from Bugzillla instead (resolved bugs marked as fixed for the
appropriate milestone). Then we'd only have to make sure periodically
that recently closed bugs without a milestone set get a milestone set.
I believe several people perform such query already and fill in the
missing milestones.
> We
can't use the commit message subject because they aren't always the same
> as what you want to write in the release notes.
So are we getting rid of the recommended less-than-50-character limit
on commit subjects? Or are we assuming that whoever volunteers to
clean up the subject-dump will expand on it as necessary?
No, the commit subject character limit is there for a good reason. We
shouldn't change that for this.
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.
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.
There are cases where it is important to write more elaborate notes
for maintenance for extension developers and migration/upgrading for
site administrators.
And yes when the release notes are processed on the wiki page, things
that need further documentation can be freely written in (for example)
an "Upgrade" or "To extension maintainers" section – instead of
scattered through the bullet point lists.
For example:
== Changes ==
* foo: Upgrade to version 1.20
* bar: Don't silently ignore invalid values in event handler
* ..
== To extension maintainers ==
Various bar plugins are known to call the event handler with an object instead
of an array containing the object. This was previously silently skipped.
This failure is now explicit by throwing an invalid arguments exception.
> Mark
entries with the relevant labels ("New", "Removed",
"Breaking" etc.)
I worry that whoever is doing this for API changes (if it doesn't wind
up being me) won't know how we determine "Breaking" for API changes.
I.e. "anything that's not backwards-compatible for API users".
"If you don't know what you're doing, don't do it?"
I think we can reasonably assume good faith that people won't go and
mislabel things on the wiki page as "breaking" for a component they
are not knowledgeable in.
Plus, it is a wiki page, so it'll be a lot easier to keep track of and
fix for everyone involved.
This will make that easier since this would basically turn to doing a
"post-merge" review of activities to some degree.
-- Krinkle