Calendar library: version 2.0

Calendar library: version 2.0

[Julien Signoles]

Hello everybody,

I am happy to announce a new release (v2.0) of Calendar, an ocaml 
library managing dates and times. This release provides a bunch of new 
modules and functions.

The library is available at:
 	http://www.lri.fr/~signoles/prog.en.html#calendar

The changes between the last version (v1.10) and this new one are:
* licence changes from LGPLv2 to LGPLv2.1
* use -pack: all modules of the library are packed inside a single module
   CalendarLib (calendar now requires ocaml >= 3.09.1)
* new modules Time_sig, Date_sig and Calendar_sig
* new module Ftime (time implementation in which seconds are floats)
   (Hezekiah M. Carty's suggestion)
* new module Calendar_builder (generic calendar implementation)
* new module Fcalendar (calendar implementation using Ftime)
* new module Calendar.Precise (calendar with a best precision)
* hash functions are provided
* new modules Printer.Ftime and Printer.Fcalendar
* modules Printer.Date, Printer.Time and Printer.Calendar respectively
   replace Printer.DatePrinter, Printer.TimePrinter and
   Printer.CalendarPrinter. These last modules still exist but are
   deprecated.
* new function Time_Zone.on
* new function Date.from_day_of_year (Hezekiah M. Carty's suggestion)
* new function Date.is_valid_date (Richard Jones' suggestion)
* new module Utils
* new module Version (information about version of calendar)
* add tags @example, @raise and @see in the API documentation

Have fun with calendar,
Julien Signoles

Re: [Caml-list] Calendar library: version 2.0

[Richard Jones]

On Sat, Feb 09, 2008 at 10:45:52AM +0100, Julien Signoles wrote:
> I am happy to announce a new release (v2.0) of Calendar, an ocaml 
> library managing dates and times. This release provides a bunch of new 
> modules and functions.
> 
> The library is available at:
> 	http://www.lri.fr/~signoles/prog.en.html#calendar

I've had a look at this now, and there are a few difficult issues with
this:

(1) Toplevel modules called 'Utils' and 'Version'.  This is really bad
because not only are you staking a claim to those module names, but
also it will prevent anyone using those module names in their own
programs (and surely that's quite common - I've got both used in my
own programs).

It's much better to call them Calendar_utils and Calendar_version
(note: underscore _not_ period).

(BTW, the same applies to 'Printer', but that's not new in this
release).

(2) Is the library source-compatible with 1.x?

Rich.

-- 
Richard Jones
Red Hat

Re: [Caml-list] Calendar library: version 2.0

[Richard Jones]

OK, I take that back.  Everything is now packed under CalendarLib.*
which makes the issue of module names moot.

Also it means nothing is backwards compatible :-(  That could be a
problem because it means I need to release two different versions of
everything which uses the calendar library, but at least that's just a
one-off event.

Rich.

-- 
Richard Jones
Red Hat

Re: [Caml-list] Calendar library: version 2.0

[Stéphane Glondu]

Richard Jones a écrit :
> It's much better to call them Calendar_utils and Calendar_version
> (note: underscore _not_ period).

Could you elaborate on this?

-- 
Stéphane

Re: [Caml-list] Calendar library: version 2.0

[Richard Jones]

On Tue, Feb 12, 2008 at 08:38:48PM +0100, Stéphane Glondu wrote:
> Richard Jones a écrit :
> > It's much better to call them Calendar_utils and Calendar_version
> > (note: underscore _not_ period).
> 
> Could you elaborate on this?

In brief, using an underscore leaves the space open.

If I have a package called:

  Net.FTP

then no one else independently can create a package called Net or
Net.Telnet (or Net.anything else).

However if I create a package called:

  Net_FTP

then an independent person can come along and make:

  Net_Telnet

Rich.

-- 
Richard Jones
Red Hat

Re: [Caml-list] Calendar library: version 2.0

[Julien Signoles]

> OK, I take that back.  Everything is now packed under CalendarLib.*
> which makes the issue of module names moot.

Indeed it is one of my arguments for packing calendar.

> Also it means nothing is backwards compatible :-(  That could be a
> problem because it means I need to release two different versions of
> everything which uses the calendar library, but at least that's just a
> one-off event.

You're obviously right: as calendar is now packed, everything which uses 
calendar v1.* does not work anymore with calendar v2.* (and vice-versa).

But the only change to do in your code is: add "open CalendarLib" at the 
top of your files and all is fine because the API is backward compatible 
inside the pack.

For your application(s), a possible trade-off is:
- do this tiny change
- release a new version requiring calendar v2.*

--
Julien

Re: [Caml-list] Calendar library: version 2.0

[Nicolas Pouillard]

[-- Attachment #1: Type: text/plain, Size: 1065 bytes --]

Excerpts from Julien Signoles's message of Wed Feb 13 10:30:47 +0100 2008:
> 
> > OK, I take that back.  Everything is now packed under CalendarLib.*
> > which makes the issue of module names moot.
> 
> Indeed it is one of my arguments for packing calendar.
> 
> > Also it means nothing is backwards compatible :-(  That could be a
> > problem because it means I need to release two different versions of
> > everything which uses the calendar library, but at least that's just a
> > one-off event.
> 
> You're obviously right: as calendar is now packed, everything which uses 
> calendar v1.* does not work anymore with calendar v2.* (and vice-versa).
> 
> But the only change to do in your code is: add "open CalendarLib" at the 
> top of your files and all is fine because the API is backward compatible 
> inside the pack.
> 
> For your application(s), a possible trade-off is:
> - do this tiny change
> - release a new version requiring calendar v2.*

Why not releasing a last version of the v1 adding an empty CalendarLib.ml?

-- 
Nicolas Pouillard aka Ertai

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 186 bytes --]

Re: [Caml-list] Calendar library: version 2.0

[Richard Jones]

On Wed, Feb 13, 2008 at 10:30:47AM +0100, Julien Signoles wrote:
> 
> >OK, I take that back.  Everything is now packed under CalendarLib.*
> >which makes the issue of module names moot.
> 
> Indeed it is one of my arguments for packing calendar.
> 
> >Also it means nothing is backwards compatible :-(  That could be a
> >problem because it means I need to release two different versions of
> >everything which uses the calendar library, but at least that's just a
> >one-off event.
> 
> You're obviously right: as calendar is now packed, everything which uses 
> calendar v1.* does not work anymore with calendar v2.* (and vice-versa).
> 
> But the only change to do in your code is: add "open CalendarLib" at the 
> top of your files and all is fine because the API is backward compatible 
> inside the pack.

It may be a tiny change, but it still needs two versions of the code
to deal with.

API changes aren't handled gracefully in OCaml.  The same thing
happens whenever the lablgtk API changes incompatibly - I end up using
the C preprocessor or Makefile hacks.

Rich.

-- 
Richard Jones
Red Hat

RE: [Caml-list] Calendar library: version 2.0

[David Allsopp]

Nicolas Pouillard wrote:
> Why not releasing a last version of the v1 adding an empty CalendarLib.ml?

That would be an appalling thing to do! The way Julien has versioned this is
exactly correct - it's a major version increment so totally incompatible
code changes are acceptable (even though, as Richard has pointed out, it
does create a little bit of pain for libraries that depend on Calendar).
That said, it's not too much work as far as I can see to hide the difference
in a module generated in a configure script... perhaps a bit of code that
could be included in Calendar to help package authors.

As things stand, I can stick with Calendar 1.10.0 until I want/need to shift
to 2.0.0 - and Julien could release any pertinent *bug-fixes* to the 1.x and
2.x branches if he wishes.

To make a change like that (even where the code alterations required are
relatively small) is IMHO not an acceptable thing to do with a minor version
increment.


David