Add verbose debug instrumentation and notes to ship_upgrades.py.

The upgrade logic itself remains unchanged/broken for now,
and the notes in the docstring only represent changes that I'm
thinking about implementing in the future.