Walter Bright, el 3 de January a las 19:18 me escribiste: > On 1/3/2013 12:27 PM, Leandro Lucarella wrote: > >BTW, Changelogs looks extremely naked now, I think release notes are > >really needed now. Al least for new features. Is far from ideal to make > >people go through a bug report to know how they can adapt their code to > >new features. > > On the other hand, the older way of doing changelogs routinely > missed a *lot* of things. Relatively few people doing the pulls > would bother to log the changes. I think there were easy double the > number of changes showing up in the search than were in the log.
I agree completely. I'm not saying having a well maintained bug tracker is a bad think! Is great, and is great to be able to automatically list all the bugs fixed in a release. Is think is a huge improvement. I'm just saying is not good enough, there is more room for improvement IMHO. > >And sometimes bug reports are not updated on how things turned out, for > >example #7041[1], a feature I implemented myself. The bug report is > >outdated AFAIK, the title talks about a -di flags which doesn't even > >exist, you actually have to go through the pull request[2] to see what > >the hell is going on. And even then the behaviour of that pull request > >was changed in a subsequent one[3], and there are no visible links > >between those 2 pull requests. > > Please update that bugzilla issue. As I posted elsewhere in this > thread, this method does require upping our game with bugzilla tags, > titles, and descriptions. > > I don't see that it is any *harder* to update the bugzilla issue > than it is to provide a brief summary in the changelog. Is harder for the **user**, not for the developer! I updated all the documentation in the compiler itself and the man page, I just never wrote changelog entries in the documentation. If you really want to make people update all the documentation, you should reject pull requests until they are **complete**. If I missed updating something is because nobody told me I had to. I'll happily update release notes in the future if you tell me where they are. > As for what's new, the failure here is the failure to document those > changes. This is not a failure of the changelog - it's a failure of > the documentation pages. The bugzilla should have a link to the > relevant documentation. Please see my other comment. I really think you're getting this wrong. Bugzilla is for internal development, not to inform people about new features. New features might end up being completely different from what the user reported in the first place, and it's very cruel to make users have to read a complete discussion about a feature (or to scroll to the end of a bug report to find a link, or even to click on 2 links for each new/changed feature!). I agree is the same work for a developer to update the documentation, being in bugzilla or in the repository, but having a proper document with at least big changes explained is much more useful to the user (and I think is even easier to edit for the developer). And then, is harder to reject pull request if they don't update some documentation in the same repo the pull request is made than checking some bugzilla report to see if is properly updated. > I do *not* think that a changelog new feature entry takes the place > of updating the documentation, and I do not agree with writing the > documentation twice (changelog and documentation). We agree on this too. I don't know why are you getting the impression I want something else in this matter. > >Anyway, at least for this particular change, the changelog is basically > >useless, and I don't think the bug report is the right place to inform > >users about compiler changes. > > We've been using bugzilla for a long time to organize enhancement requests. And that's perfect too. > >Users don't care about the history and > >discussion around a change, they just only want to know how to take > >advantage of new features and how to fix their code (possibly with some > >exceptions of course, in which case they can still go back to the bug > >report and pull requests). > > I agree this new system is imperfect - but I argue it is better than > what we were doing before. And I'm not suggesting going back to where we were before, just keep improving. What I'm suggesting is: * Keep handling *all* development (bugfixes and new features) through bugzilla * Keep listing bugfixes and new features lists automatically as bugzilla queries (I think it would be better to automatically generate a nicer document with those lists though, but that's just details) * Keep having the complete documentation for new features where it should be (the website/specs). * Add a release notes documents (that could be also the base to announce releases with more details in the e-mail release) which gives a brief summary of the focus of the current release and any important changes visible to the users. When new features are added, include the link to the proper documentation. * Reject pull requests that don't update either the documentation or the release notes, but TELL people what's missing for the pull request to be merged, so they learn how to do pull requests that are complete. * Review the release notes just before the release to make it coherent. Another good example of release notes is the LLVM project. Please, take a look at Python release notes and LLVM release notes if you haven't before. Just take a look. Examples: http://python.org/download/releases/3.3.0/ http://llvm.org/releases/3.2/docs/ReleaseNotes.html (this link might be wrong because I can't access the llvm website right now to check) -- Leandro Lucarella (AKA luca) http://llucax.com.ar/ ---------------------------------------------------------------------- GPG Key: 5F5A8D05 (F8CD F9A7 BF00 5431 4145 104C 949E BFB6 5F5A 8D05) ---------------------------------------------------------------------- Cómo ser inconmensurablemente atractivo a la mujer del sexo opuesto. -- Libro de autoayuda de Hector Mesina.
