Documentation for upgrades

[sveitser]

Add a markdown file in the doc folder that describes in some detail how upgrades work.

[tbro]

I think code should also be documented. This isn't very useful to me. As a general process I would like to suggest we dial up considerably the documentation we add when modifying code. This includes both doc comments and regular comments. The markdown files in the doc folder can then lift and amplify information from these comments.