I have not been involved in a migration, but I have contributed to the YUI 3 gallery, and I also know there is a gallery entry that allows any class from YUI 2 to be used in YUI 3. I guess the main advantage of YUI 3 is the ability to load in what you want on demand. You include 1 javascript file, and then would use the following line to use whatever modules in yui you want.
YUI().use('dom',function(){
// your code here
});
The advantage of this is it laods the DOM module, and makes available ONLY in the scope of that function. This is good because it only loads the modules you want in a specific scope. This will prevent clashes with any other JS frameworks if you use them.
If you want to add your own custom module you would do something like this
YUI().add('mycustompackage',function(Y){
MyCustom.package.SomeClass = function(){}
MyCustom.package.SomeClass.prototype = {}
},'1.0.0',{requires:['base','dom','event'],use:['node']});
That will add your module, and register the dependencies, so then you can use it by saying
YUI().use('mycustompackage',function(){
// code goes here
});
I guess from what I can see, the main advantages are a more secure and portable framework. You can make the YUI 3 modules available ONLY within a given function scope. THis frees up the main scope of the page for other things if you wish. Its also more secure, the definition of your functions are in a private scope, so they have no global variable hooks to be exploited by say script injection or what not.