You're not breaking CPAN but your modules on CPAN :)

Also, there is no "Foo" module on CPAN :)

But you have two choices -- break it, and let the chips fall where they may -- or maintain API compatibility (  HTML::Parser->new( api_version => 3, ... )

So, you've decided to change things, great, do whatever you feel will cause the least pain for those (if any) users of your code

a logical way would be to keep both old and new versions independent but I don't see a way to do that with CPAN

Sure you do, make a new namespace, as in Foo2

It basically comes down to promises you made :) If you warned users that API may change in future versions, then they were warned :)

Piece of advice, if your docs/tutorials/videos... are outdated with respect to the current working API, go with the rename ... invalidating existing docs/tutorials with API changes is super weak self inflicted stupidity regardless of the promises you made ... if you can't delete the videos rename :)

See also Update module and break api, or change namespace

I think whatever your product, rename is the simplest, think fork