On Fri, May 3, 2013 at 1:02 PM, Krinkle <[email protected]> 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 _______________________________________________ Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
