Update module and break api, or change namespace

leocharre has asked for the wisdom of the Perl Monks concerning the following question:

I have a package called PDF::OCR which was written a while back. The module worked well for my purposes, I wanted other people to have access. I makde sure to note that it was a development version.

Later on when I had developed the code better- simplified the package- I realized that api was not compatible with the old PDF::OCR.

A number of people were using PDF::OCR, and I didn't want to release a version that would break their code. So I released PDF::OCR2, a better tool, that does the same work, better- with a differnt api.

Since, I have received various questions, complaints, inquiries as to why there is a PDF::OCR and a PDF::OCR2.
I would like to do the right thing, and release a new version of PDF::OCR with the updates.
It's going to break the code of anyone interfacing with the old version.

Should I keep things the way they are, label PDF::OCR as deprecated, or have some discipline and no mercy- and just update PDF::OCR.

I feel a little retarded that the api did not stay the same. I'm sorry. It was just a complex procedure, and I ended up separating the code into smaller and properly manageable modules.

Comment on Update module and break api, or change namespace

Replies are listed 'Best First'.
Re: Update module and break api, or change namespace by eye (Chaplain) on Dec 31, 2008 at 07:58 UTC
Should I keep things the way they are, label PDF::OCR as deprecated [...] YES. Even though we label things as "in development," when we release the code, we have to expect that at some point people will start to regard it as "stable." If you deprecate this module now, these people can continue to use it as long as they want. If you change the API and introduce changes that are incompatible with the old code, you create small management headaches for people that aren't prepared to or are unable to rewrite an application to use the new code base. Moreover, if someone identifies a serious bug in the old version, how do you fix it for the people that did not upgrade? If someone else offers to maintain the "old" code, how would they be able to fix it? It's not impossible, but at best it will be horribly confusing. More likely it will make people rip their hair out and curse the day you were born. The harm of changing the namespace is inconsequential compared with the potential harm of not changing it. You did do the right thing. Anyone that doesn't understand that should receive a full refund of all monies that they paid you for your development efforts on PDF::OCR. They are also welcome to create a branch of PDF::OCR and do things the way they think it should be done. (Maybe they could call their branch PDF::OCR3....)	[reply]
Re: Update module and break api, or change namespace by hangon (Deacon) on Dec 31, 2008 at 05:59 UTC
Should I keep things the way they are, label PDF::OCR as deprecated ... Yes. You went through some trouble (and took some undeserved crap) to avoid breaking other peoples code. ++ Going back now and breaking that code, for no reason other than some people do not like the PDF::OCR2 namespace, is not the right thing. Also, what about the people using PDF::OCR2? Will they now need to "upgrade" to PDF::OCR? IMHO, its easier and less troublesome for everyone involved if you just continue on the path you started. Just update the docs to state that PDF::OCR is depreciated and no longer maintained, and PDF::OCR2 should be used for new projects.	[reply]
Re: Update module and break api, or change namespace by sflitman (Hermit) on Dec 31, 2008 at 05:56 UTC
Like St. Larry says, there's more than one way to do it. Don't be sorry about breaking the API, that's why you have a different namespace. I love PDF::OCR by the way, use it every day with Tesseract. I'm going to check out PDF::OCR2, is it much faster? SSF	[reply]
Re: Update module and break api, or change namespace by Your Mother (Archbishop) on Dec 31, 2008 at 17:00 UTC
I'd say you did the right thing. But I think you miss the chance for a better namespace. I can intuit what PDF::OCR does because there isn't anything else it could sensibly do but a name like PDF::Extract::OCR or PDF::Parse::OCR would be a bit more semantic. So I say. :)	[reply]
Re: Update module and break api, or change namespace by puudeli (Pilgrim) on Dec 31, 2008 at 06:05 UTC
Why both APIs can not co-exist? Re-invent the function/method names for the upgrade. One of the holy rules with interfaces and libraries is that the API does not change between versions. Just do all you can to retain backward compatibility. -- `seek $her, $from, $everywhere if exists $true{love};`	[reply] [d/l]
Re^2: Update module and break api, or change namespace by Anonymous Monk on Dec 31, 2008 at 13:13 UTC
Just do all you can to retain backward compatibility. Or do nothing :)	[reply]