#419, #420: upgrading, upgrade macro development, upgrade documentation

This adds tutorials for:
 * upgrade usage (#419)
 * upgrade macro development (#420)

It also adds some API documentation for the upgrade macro base class.