Maybe it's because of Serenity. Maybe not. But since my hope is that you have journals here to talk about Perl, rather than blogs over $there to talk about your cat, and you read the journals to learn a few things, I'd like to share a little learning today, on the subject of leaving home.
When you leave home, you can never go back.
I don't mean to visit, I mean to stay. Once you've left the protected confines of the family nest where you grew and changed, you should never go home other than to visit. It just doesn't feel right, and it can cause a lot of frustration, and sometimes pain. You just don't fit any more.
And this is exactly the way it is with your APIs.
Any piece of software, particularly those you put on CPAN, are actually two products. The most important of these is the API. This represents what is really a contract between you and your users.
"Take these step, and $this will happen"
This is written not in code, but in the POD. The code is really secondary, an implementation detail you get lumped with when you buy the API.
In the rush towards the fun of getting your cool idea used by other people on CPAN, people often miss the distinction and rush code out unfinished.
Implementations are allowed to be crap. You can test it badly, implement it inefficiently, leave security holes, anything you like. You can patch your code up later and nobody gets hurt.
The absolute opposite is true for APIs. Once they leave, they can never come home, and you don't get to change them.
This isn't an absolute of course.
Just like leaving home, you can change your mind. Change your API within a day of putting it on CPAN and it's nothing, change it in a month and the early adopters will be happy with it. Change it in three and people won't mind.
Change your CPAN API after a year, and if you've built up any sort of a userbase, you are causing the very people you posted the code to help pain. One of the worst things you can do is deliver an API that is sorta right and does the job, kinda but really should be completely different. Then get distracted on other projects for a year, and come back to "fix" the API. Too late.
Because by now people that used your module for real code have moved on to other things. They solved their problem with your nice mostly stable module, and they can't remember how exactly they wrote it any more. Remember Damian's violent psychopath? It's you in 6 months. And it's your users when you change the API 6 months after they used it.
That isn't to say you can't do anything. You can always add, and do other things that doesn't change your contract with the current users.
As we've found with Test::More in the last few days, sometime you've delivered APIs you didn't even know were APIs. Despite stating in the document that it might change, after staying the same for 4 years about a third of CPAN and most of the testing infrastructure came to rely on a particular error message from Test::More. In a nutshell, it was being used to confirm that when a testing module returned an expected test failure , it failed at exactly the line the author wanted to trigger it from.
And when it changed, it hurt like the dickens, although in this case it was more like a poison and was taking time to gradually build up the pain.
After 7 or 8 less then impressive plans to fix the problem (by various people me included), Schwern finally came up with a brilliant and cunning out-of-left-of-field plan to fix it properly. Of course he's had to annex the small country next door, but it does solve the problem properly, thoroughly and elegantly. Schwern++
So be mindful. Do what you want with the code, but don't let your APIs escape onto the CPAN until you are comfortable they are stable. And if the API is going to shaped by the implementation, as it was for PPI, then maybe you have to wait 3 years until you get to push it over the wall. So be it. It's best for everyone this way.
It's fine to talk about history, but if you want a much much bigger example, what I hope you might find interesting is to watch the process for a real system? How about it? :)
In the next few days, Sachmet and I are going to be announcing a new, huge project. Something that it would be nice to see as one of next year's Big Things in the Perl community. And it's going to take quite a number of people to get it done, from coders to expert sysadmins to normal people that just want to lend a hand.
To be honest, if it comes off anything close to it's potential I will be majorly impressed. It should make PPI look like a cute little toy in comparison.
But it needs to be specified first. Something this big you absolutely need to have all the APIs solid (or at the very least sketched out) before you start.
In this case, that means 2 to 3 file formats, a couple of communications protocols, and about 10 Perl module interfaces. They all need to be speced out properly, because once they escape from the nest, once we start to get people using them, there's 2 or 3 that would be inordinately painful to change them.
So far I've spent about 13 hours working to complete a rough first draft of the overall system. Im cajoling the other members of the Perl testing community into reviewing it right now. So stay tuned, I can't wait. This is going to be one VERY fun project. :)
