Document upgrade strategy

[yuvipanda]

People should be able to upgrade 1 minor version of TLJH installations.

• Decide on & document our upgrade strategy
  • Users are to run bootstrap.py script from tljh's main branch from where they can specify the version they wish to install/upgrade to.
  • The Hub envs python packages gets upgraded, but the user env is touched as little as possible
• Document various components & how they would react to upgrades
  • The changelog in Add changelog for 1.0.0b1 #888 mentions this
• Write upgrade documentation
  • Resolved by docs: add docs about environments and upgrades #932
• Document what to do if we want a 'wipe everything and start over, but preserve user data' upgrade
  • Still needed as of 2023-08-10, this issue is closed by docs: add docs about environments and upgrades #932 without addressing this

---

Related

• Handling versions and releases #724
• Document an upgrade procedure for an active TLJH deployment #204

[yuvipanda]

I think the general upgrade strategy is to run the installer again, and that 'ensures' everything to where it should be. This means we need a way in the installer to:

1. Tell what the current version is
2. Refuse to upgrade if it is unsupported
3. Upgrade various components as atomically as possible
4. Always have option of 'blow everything away and re-install it' without losing any user state.

[choldgraf]

Plan is to include this in v0.2, since we don't necessarily want to "freeze" an upgrade pathway yet until we see more usecases out of TLJH.

[nsurleraux-railnova]

If anything, I would love to have my installation backed up so that if an upgrade borks it, we can always restore it to the latest working state. (It could be automated or part of the documented upgrade process).

In the requirements-user-env-extras.txt file, it is clearly written that TLJH won't upgrade those libraries if TLJH is upgraded. The documentation should explain why it won't be upgraded (as users can upgrade/downgrade them). I think it would be reasonable in the upgrade documentation to have a table with the versions of the TLJH against the recommended versions of the libraries in the user env.

(EDIT: https://github.com/jupyterhub/the-littlest-jupyterhub/pull/888/files?short_path=3bd14d0#diff-3bd14d078188074c410028847113ceae68865d0ad5b844a27183ef87fbe2fcc3 seems to already include a table with the user env version upgrade)