jonathan, you do have a fair point -- i already have to edit that file each time i upgrade, as you say, to change the application and version, as well as add in some handlers for gae. so it's not that big a deal to go in and do this as well, so long as i know to do it.
but i think your second point is better -- making this app.example.yaml is a good idea. in this case, i will suggest that this latest change meant web2py wasn't backwards compatible for me; i did all the things i normally do for an upgrade and my program stopped working. if something like that were to happen in the future, and it would cost a couple hours to figure out what, it would be problematic. a flipside, like with routes, is that you'd need to have some form of default included for first-timers. perhaps when web2py starts it checks to see if app.yaml exists, and if not, copies app.example.yaml to app.yaml. but i don't know how complicated that is. you all know better than i how to handle the tradeoffs because you're closer to it, but it will certainly make my life simpler if i don't have to worry that a new app.yaml will cause unintended problems. thanks for your help and i look forward to seeing which solution makes the most sense. matt