1) Datetime website 2) recommended practice to alter API

Discussion:

(too old to reply)

Jean Forget

2013-09-27 05:30:35 UTC

When I try to access the http://datetime.perl.org/wiki/datetime/
website, I get:
--- begin of copy-paste
Service Temporarily Unavailable
The server is temporarily unable to service your request due to
maintenance downtime or capacity problems. Please try again later.
--- end of copy-paste
Can you check the web server, please?

----------

I wanted to find if the website has any advices on programming
or on managing module releases. My present concern is
https://rt.cpan.org/Public/Bug/Display.html?id=77710
replacing the API keyword "iteration" with "precise"
in DateTime::Event::Sunrise. And I have at least one other
keyword change (altitude -> height)
The various steps would be:
1) silently accept both old and new keywords
2) accept both keywords, but emit a warning if the old keyword is used
3) accept only the new keyword.

My questions are:
-- how much time should pass between two steps?
-- in step 1, should the module emit a warning if both keywords
are used at the same time? (I think yes)

Another question is: which is the earliest Perl version
should we target? Dave wanted to target 5.005 or maybe 5.004,
but that was more or less 10 years ago, when the 5.8 version
was reigning supreme. But now, we have reached 5.18 and
5.14 is no longer officially supported.

Jean Forget

Zefram

2013-09-27 12:05:12 UTC

Permalink

Post by Jean Forget
-- how much time should pass between two steps?

In situations like this, I'd accept the old keyword forever, never even
making it warn. The ability to use the clearer keywords is a desirable
feature, but not a good reason to make the original keywords stop working.

Post by Jean Forget
-- in step 1, should the module emit a warning if both keywords
are used at the same time? (I think yes)

It should be a hard error, generating an exception, not a warning.

Post by Jean Forget
Another question is: which is the earliest Perl version
should we target?

Depends on the target audience. You shouldn't go to extra effort to
support anything earlier than around 5.12 unless you have a specific user
who can't upgrade Perl. Targeting earlier than 5.6 is a pain because the
"our" keyword isn't available earlier. Personally I routinely test my
CPAN modules against almost all versions back to 5.6.1, but I'm unusual
in that regard.

-zefram

Dave Rolsky

2013-09-27 14:04:57 UTC

Permalink

Post by Jean Forget
When I try to access the http://datetime.perl.org/wiki/datetime/
--- begin of copy-paste
Service Temporarily Unavailable
The server is temporarily unable to service your request due to
maintenance downtime or capacity problems. Please try again later.
--- end of copy-paste
Can you check the web server, please?

My server crashed hard on Monday. I've moved to Linode but I haven't quite
gotten everything running again.

Post by Jean Forget
Another question is: which is the earliest Perl version
should we target? Dave wanted to target 5.005 or maybe 5.004,
but that was more or less 10 years ago, when the 5.8 version
was reigning supreme. But now, we have reached 5.18 and
5.14 is no longer officially supported.

I'd say 5.8 or 5.10. Unfortunately, while p5p may only support 5.16+,
there are still distributions in wide use like RHEL that use old Perls.

-dave

/*============================================================
http://VegGuide.org http://blog.urth.org
Your guide to all that's veg House Absolute(ly Pointless)
============================================================*/

Jim Bacon

2013-10-05 03:08:20 UTC

Permalink

I agree with Dave on this one. Unless there is some feature in a new version
of Perl that I just have to have (usually in my work environment where we
have full control over all machines) I try to write code that will run on
5.8.x (or more recently 5.10.x) if it is destined for CPAN or other public
consumption. There are shared hosting providers that have just recently
upgraded from 5.8.8 to 5.10 (I can think of two MAJOR providers.) Yes, one
can always run perlbrew, but that is not always a reasonable option in a
hosted environment.

Jim

-----Original Message-----
From: Dave Rolsky [mailto:***@urth.org]
Sent: Friday, September 27, 2013 9:05 AM
To: Jean Forget
Cc: ***@perl.org
Subject: Re: 1) Datetime website 2) recommended practice to alter API

My server crashed hard on Monday. I've moved to Linode but I haven't quite
gotten everything running again.

Post by Jean Forget
Another question is: which is the earliest Perl version should we
target? Dave wanted to target 5.005 or maybe 5.004, but that was more
or less 10 years ago, when the 5.8 version was reigning supreme. But
now, we have reached 5.18 and
5.14 is no longer officially supported.

I'd say 5.8 or 5.10. Unfortunately, while p5p may only support 5.16+, there
are still distributions in wide use like RHEL that use old Perls.

-dave

/*============================================================
http://VegGuide.org http://blog.urth.org
Your guide to all that's veg House Absolute(ly Pointless)
============================================================*/

Olivier Mengué

2013-10-01 16:19:34 UTC

Permalink

Post by Jean Forget
I wanted to find if the website has any advices on programming
or on managing module releases. My present concern is
https://rt.cpan.org/Public/Bug/Display.html?id=77710
replacing the API keyword "iteration" with "precise"
in DateTime::Event::Sunrise. And I have at least one other
keyword change (altitude -> height)
1) silently accept both old and new keywords
2) accept both keywords, but emit a warning if the old keyword is used
3) accept only the new keyword.

Just mark the old keywords as deprecated in the documentation (or even
remove them completely after a few releases and a warning in the
Changes file).
In the code, accept both the old and new keywords forever and don't
try to apply technical measures to enforce that the new keywords are
used: your API users (or the users of your users, or their users)
don't deserve that pain.

Olivier Mengué.