Re: API changes on TnyAccountStore

[Philip Van Hoof <spam pvanhoof be>]

On Sun, 2007-04-29 at 13:45 +0200, Philip Van Hoof wrote:
> On Sun, 2007-04-29 at 13:43 +0200, Philip Van Hoof wrote:
> > On Sun, 2007-04-29 at 13:42 +0200, Philip Van Hoof wrote:
> 
> Forwarding this from private discussions:
> 
> Murray Cumming wrote:
> 
> > Although I too believe the ChangeLog is important, I don't see it as a
> > location for this type of documentation. Rather as a little database
> > with "what has changed", not software development guidelines.
> 
> Yes. It didn't show what had changed.
> 
> I've figured it out now, anyway, having read your email properly.

Ok. We can make it a rule on the Tinymail project to enforce being a
little bit descriptive in the ChangeLog file. Although I didn't do it
for this changeset, I indeed agree with you that this is important too.

Guidelines on how to deal with the change, though, don't belong in that
file. Although referencing to documentation that does describe how to
deal with the changes, does belong in that file, in my opinion.

-> I see the ChangeLog as a quick overview of changes. A listing.

> > I rather see the mailing list and the trac wiki as a more ideal location
> > to inform people about changes like this.
> > 
> > Maybe we can add a "API changes since last version" section to each page
> > on the trac wiki? Or a "Porting from 1.0" page, once there is a first
> > release.
> 
> Yes, that's what NEWS is for. Or at least, that's what I do with gtkmm.

I'd feel comfortable if it would be put in NEWS, yes. But I haven't used
NEWS a lot (in my career). Neither written to nor read it.

I, personally, usually Google for this. Or read the available documen-
tation and mailing lists (for Tinymail, that's the trac wiki, the API
reference manual and its mailing list).

So if NEWS can be synchronised with any of those tools, (and it can),
I'd be comfortable with that.

-- 
Philip Van Hoof, software developer
home: me at pvanhoof dot be 
gnome: pvanhoof at gnome dot org 
http://www.pvanhoof.be/blog