You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@perl.apache.org by Stas Bekman <st...@stason.org> on 2004/02/24 03:56:13 UTC
how to make 2.0 release sooner
Besides resolving several remaining issues listed in modperl-2.0/todo/release
and solving bugs as they are reported, the only real showstopper for 2.0
release is the API finalization. As we have discussed here multiple times we
might not be able to release a complete Apache 2.0 API, but only a subset of
it, with further APIs released post-mod_perl 2.0 release. Since we have lots
of APIs which are untested and undocumented, we aren't going to include those
in the official API (read: they will be unsupported and may change).
So, we need to start working on the API finalization. That means going through
functions, constants and methods at http://perl.apache.org/docs/2.0/api/,
taking each item, checking that it's fully documented and tested. If not the
missing documentation and/or missing tests need to be written.
If we distribute the effort and each one of us does one function a day
or so, in a few months we may be able to get the majority of the functions
covered, and we will be ready for the 2.0 release.
Everybody is welcome and invited to help to bring the release date to a sooner
date. If we get enough help we may need to run some sort of wiki to coordinate
the effort, so two people don't get to work on the same function.
Of course start with low hanging fruits: i.e. those that are already well
tested, documented and if not documented in 2.0, 1.0 docs might be of help.
http://perl.apache.org/docs/1.0/api/.
You are absolutely welcome to ask for help here. But, please, don't just go to
some obscure function and ask here what does it do. To answer the question we
will need to research the issue, write tests and essentially do the whole
thing. So please work on functions that you do understand and have experience
with (at least in the mp1 world).
If you ask for help please start a new thread for each function.
I need to update the doc template, but these and other already documented
methods will give you a good idea on how to do it:
http://perl.apache.org/docs/2.0/api/Apache/RequestRec.html#C_proxyreq_
http://perl.apache.org/docs/2.0/api/Apache/RequestUtil.html#C_get_handlers_
The items that need to be taken care of are all marked with:
META: Autogenerated - needs to be reviewed/completed
once you are done, remove that comment. If you are mostly done but something
is missing you can mark with another META: tag...
You will want to work with the cvs repository, which you can read on at:
http://perl.apache.org/download/docs.html
Remember not to edit to html, but to work with pod files, as the former is
autogenerated.
Also remember that a documented but not a fully tested function is not a happy
function. It's the best to get the tests and documentation at once for each
function. For more information on how to write tests see:
http://perl.apache.org/docs/general/testing/testing.html
http://www.perl.com/pub/a/2003/05/22/testing.html
I hope that I didn't make it sound too scary or demanding and you will be
willing to give a bit of your time and may be learn a thing or two on the way.
Thank you.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: how to make 2.0 release sooner
Posted by David Wheeler <da...@kineticode.com>.
On Feb 24, 2004, at 11:40 AM, Stas Bekman wrote:
> Unfortunately for me, Geoff is already taken by a beautiful girl, who
> gave him two gorgeous flowers ;)
Ah, pity for Stas. ;-)
D
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: how to make 2.0 release sooner
Posted by Stas Bekman <st...@stason.org>.
David Wheeler wrote:
> On Feb 24, 2004, at 11:06 AM, Stas Bekman wrote:
>
>> That's exactly what I have on my mind. Sorry for not conveying that
>> clearly.
>
>
> So nice to see you two kiss and make up! ;-)
Unfortunately for me, Geoff is already taken by a beautiful girl, who gave him
two gorgeous flowers ;)
> David, who is very much looking forward to mod_perl 2.0 and apreq 2.0
;)
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: how to make 2.0 release sooner
Posted by David Wheeler <da...@kineticode.com>.
On Feb 24, 2004, at 11:06 AM, Stas Bekman wrote:
> That's exactly what I have on my mind. Sorry for not conveying that
> clearly.
So nice to see you two kiss and make up! ;-)
David, who is very much looking forward to mod_perl 2.0 and apreq 2.0
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: how to make 2.0 release sooner
Posted by Stas Bekman <st...@stason.org>.
Geoffrey Young wrote:
>>Where did you see me saying 'closing off parts of the API'?
>
>
> that was my reading of "we might not be able to release a complete Apache
> 2.0 API, but only a subset of it, with further APIs released post-mod_perl
> 2.0 release."
>
> if you mean to include the entire Apache API in the official 2.0 but only
> "commit" to a subset of it (as in "the subset is frozen but the remaing
> parts still exists and are available to users without modification of the
> sources") then I'm fine with it and appologize for my misunderstanding.
That's exactly what I have on my mind. Sorry for not conveying that clearly.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: how to make 2.0 release sooner
Posted by Geoffrey Young <ge...@modperlcookbook.org>.
> Where did you see me saying 'closing off parts of the API'?
that was my reading of "we might not be able to release a complete Apache
2.0 API, but only a subset of it, with further APIs released post-mod_perl
2.0 release."
if you mean to include the entire Apache API in the official 2.0 but only
"commit" to a subset of it (as in "the subset is frozen but the remaing
parts still exists and are available to users without modification of the
sources") then I'm fine with it and appologize for my misunderstanding.
--Geoff
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: how to make 2.0 release sooner
Posted by Stas Bekman <st...@stason.org>.
Geoffrey Young wrote:
>
> Stas Bekman wrote:
>
>>As we have
>>discussed here multiple times we might not be able to release a complete
>>Apache 2.0 API, but only a subset of it, with further APIs released
>>post-mod_perl 2.0 release. Since we have lots of APIs which are untested
>>and undocumented, we aren't going to include those in the official API
>
>
> when we discussed this, I disagreed with that idea. and I still do.
>
> http://perl.apache.org/docs/2.0/user/design/design.html#Perl_interface_to_the_Apache_API_and_Data_Structures
>
> "The goal for 2.0 is to generate the majority of xs code and provide thin
> wrappers where needed to make the API more Perlish. As part of this goal,
> nearly the entire APR and Apache API, along with their public data
> structures is covered from the get-go."
>
> releasing a subset of available methods is a major step backwards, taking us
> to the days of mp1 when APIs were added over time as users complained or
> developers had time - that mp2 exposes everything up front is a good thing
> and was part of the mp2 mantra from the start.
We release all the available APIs, but we commit only to those that are
documented and tested. Since you don't have tests for some new APIs you have
no clue whether the glue APIs is good or not. How can you commit to something
you don't know?
On the other hand if you think that you will be able to finish off the
complete Apache and APR APIs, than forget about 2.0 release any time soon.
Let's say 2 years later we will get it out? And what will be the gain? None.
You will spend time working on some obsure method that chances are nobody is
going to use. Sure, give it to them and they will come. But remember that the
majority is too scared to use 1.99_xx, they want 2.0 to be out.
So completing a reasonable subset of the API (mp1 API plus new
interesting/useful API) and getting 2.0 out sounds like a very sound idea to me.
>>(read: they will be unsupported and may change)
>
>
> I agree with this, but it is very different than closing off parts of the API.
Where did you see me saying 'closing off parts of the API'?
> while in some sense I understand the hesitation to expose methods that don't
> have tests ("untested features don't exist" is one of the XP ideals, IIRC).
> however, at some point we need to have faith in the code generation process
> and accept that autogenerated methods work sufficiently to support their
> release in the wild. otherwise, I see no point in autogenerating code at all.
Faith in the autogenerated code? What are you talking about Geoff? That works
if you are talking about some get/set accessors which need to extra
manipulation. But any other APIs can be so different and unsuitable to be used
as is.
> balancing robust code with rich features is often a challenge, especially in
> an application as complex as mod_perl. but I would rather offer up a full
> API that users can try out, experiment with, and offer insights into, than
> one that is incomplete save for APIs we (of limited resources) find the time
> or inclination to write tests for.
>
> I guess my own view on mod_perl as a whole goes something like this:
>
> "this is open-source and community-based software. while the development
> team has done (and continues to do) our best to ensure that the software is
> both capable and robust, there are only so many developers with so many
> available hours. thus, not every aspect of the software has been excercised
> as much as the developement team would like. if you find a bug, send a bug
> report and we will do our best to make it right."
Again, you don't undestand what I'm trying to say. Let me repeat it again.
When you release 2.0 you commit to the API. You can't change it afterwards.
I suggested to mark only the parts of the API that we can commit to that it
won't change as released. The rest are still there but marked as experimental
and are subject to change and sometimes could be even removed.
Are we on the same line now?
As for marking, I'm thinking to use Gerald's original suggestion, i.e. to have
a doc field: 'since:'
So any APIs approved for 2.0 will have:
since: 2.00
Any APIs polished and approved for 2.01 will have:
since: 2.01
etc.
I'm thinking to skip 1.99_xx and start putting 2.0 right away as we polish
them. Or we could put the appropriate 1.99_xx to help current users and then
bump the tags up to 2.0 at once just before 2.0 is released.
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org
Re: how to make 2.0 release sooner
Posted by Geoffrey Young <ge...@modperlcookbook.org>.
Stas Bekman wrote:
> As we have
> discussed here multiple times we might not be able to release a complete
> Apache 2.0 API, but only a subset of it, with further APIs released
> post-mod_perl 2.0 release. Since we have lots of APIs which are untested
> and undocumented, we aren't going to include those in the official API
when we discussed this, I disagreed with that idea. and I still do.
http://perl.apache.org/docs/2.0/user/design/design.html#Perl_interface_to_the_Apache_API_and_Data_Structures
"The goal for 2.0 is to generate the majority of xs code and provide thin
wrappers where needed to make the API more Perlish. As part of this goal,
nearly the entire APR and Apache API, along with their public data
structures is covered from the get-go."
releasing a subset of available methods is a major step backwards, taking us
to the days of mp1 when APIs were added over time as users complained or
developers had time - that mp2 exposes everything up front is a good thing
and was part of the mp2 mantra from the start.
> (read: they will be unsupported and may change)
I agree with this, but it is very different than closing off parts of the API.
while in some sense I understand the hesitation to expose methods that don't
have tests ("untested features don't exist" is one of the XP ideals, IIRC).
however, at some point we need to have faith in the code generation process
and accept that autogenerated methods work sufficiently to support their
release in the wild. otherwise, I see no point in autogenerating code at all.
balancing robust code with rich features is often a challenge, especially in
an application as complex as mod_perl. but I would rather offer up a full
API that users can try out, experiment with, and offer insights into, than
one that is incomplete save for APIs we (of limited resources) find the time
or inclination to write tests for.
I guess my own view on mod_perl as a whole goes something like this:
"this is open-source and community-based software. while the development
team has done (and continues to do) our best to ensure that the software is
both capable and robust, there are only so many developers with so many
available hours. thus, not every aspect of the software has been excercised
as much as the developement team would like. if you find a bug, send a bug
report and we will do our best to make it right."
--Geoff
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@perl.apache.org
For additional commands, e-mail: dev-help@perl.apache.org