[avr-libc-dev] dox status and next release

[Theodore A. Roth]

Hi,

I think we're in the home stretch now on the documentation. We've made
considerable progress (mostly due to Joerg ;-) and have a pretty decent
document now.

Here's what I see that still needs to be done (from doc/TODO):

 - Doxument the following:
   * introduction
   * building and installing tools for win32
   * how to pre-program the EEPROM.
   * merge chapter 3 (startup code discussion) from Rich Neswold's doc.
     Needs some rewriting to update for newer tools.
   * interfaces in:
     + include/math.h
     + include/avr/crc16.h  ???
     + include/avr/delay.h  ???
     + include/avr/ina90.h  ???
     + include/avr/timer.h  ???
     + include/avr/twi.h (move to examples?)
     + include/avr/wdt.h (move to examples?)
     + include/avr/parity.h (move to examples?)
   * gcrt1.S ???
   * the mechanism behind include/avr/io*.h ???

The last two are of questionable value. The only big one is the win32
which I think soneone sent me something about (have to check my email
rats-nest at home).

If we can knock off the rest of these, I think we'll be ready for a new
release. It looks like gcc-3.3 is set to branch on Oct 15
<http://gcc.gnu.org/develop.html#stage3> (Marek, how realistic is that?).
Once the 3.3 branch is created, I think we can make a release with the
caveat that the users need to use a gcc-3.3 snapshot (which should be
readily available).

I've also been thinking about the versioning of avr-libc. I'd really like
to change away from using the date for the version. It makes it difficult
to have multiple branches. Thus, I'd like to move to something like this.

Make the next release 1.0.0, and cut a 1.0.0 branch. Then all 1.0.x
changes are strictly bug fixes and possibly new devices, but no changing
of interfaces nor deleting/moving of files.

Once that branch is cut, the head becomes 1.1.<date>-cvs. Where date is
bumped regularly as it is now. Developers can do whatever surgery is
needed on the head. Once we're ready for another release, it would be
branch 1.2.0. If changes are drastic enough, bump it to 2.0.0.

If our branches some what coincide with gcc branches, then we can say use
avr-libc-1.0.x with gcc-3.3.x, avr-libc-1.2.x with gcc-3.4.x, etc. This
would also allow for more drastic changes in binutils/gcc since we can
track them more easily without disturbing the users.

A down side I see is for package maintainers. E.g. how does rpm
know that 1.0.0 is newer than 20021015? If this is a huge problem, we
could just rename the distributiion to navr-libc (n for new). But I'm not
too keen on that. How does debian/freebsd handle stuff like this?

Another downside is (a slight) increase in work for the maintainers.

The major win is for the users. If they start working on a project with
avr-libc-1.0.x, they're gauranteed that avr-libc-1.0.x+1 won't break
they're project and the differences from 1.0.x to 1.2.x should be well
documented so migration to newer tools is less painful than now.

Comments?

Ted Roth