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:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com http://modperlbook.org http://apache.org http://ticketmaster.com
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
