XXX add block comment describing upgrade handling