Re: [brlcad-devel] Another BRL-CAD 7.20.4 Gotcha!

[brlcad <br...@ma...>]

On Dec 01, 2011, at 02:16 PM, Tom Browder <tom...@gm...> wrote:

> After getting a good Debian build with 7.20.4, I proceeded to
> recompile my using program and came to a screeching halt with an
> error. After some time tracking it down I found the new BRL-CAD macro
> IGNORE was interfering with my use of the name--and I changed to a
> lower-case version.
>
> What's the chance of perhaps adding new macro names into NEWS (or the
> release notes) for each new version?

Both NEWS and the (NEWS-derived) release notes intentionally only cover non-developer user-visible changes.  If we inject developer-centric information, users will be the first to stop reading the "mumbo jumbo" it's a bigger concern to keep users aware of changes.  Devs adapt more easily.  That said, we don't really have a system in place for notifying API changes other than declaring when public API is changed or scheduled for removal via the doc/deprecation.txt file.

If we had Doxygen spitting out documentation with each release, it would probably be feasible to detect and emphasize API changes with some scripting.  Gray-out deprecated, cross-out obsolete API, highlight new API, etc.

Cheers!
Sean