add "upgrade guide" sections to transition docs