gluon/docs/dev/upgrade.rst

Upgrade scripts
===============

Basics
------

After each sysupgrade (including the initial installation), Gluon will execute all scripts
under ``/lib/gluon/upgrade``. These scripts' filenames usually begin with a 3-digit number
specifying the order of execution. Note that the script files need to be executable.

To get an overview of the ordering of all scripts of all packages, the helper script ``contrib/lsupgrade.sh``
in the Gluon repository can be used, which will print all upgrade scripts' filenames and directories. If executed
on a TTY, the filename will be highlighted in green, the repository in blue and the package in red.

Best practices
--------------

* Most upgrade scripts are written in Lua. This allows using lots of helper functions provided
  by Gluon, e.g. to access the site configuration or edit UCI configuration files.

* Whenever possible, scripts shouldn't check if they are running for the first time, but just edit configuration
  files to achieve a valid configuration (without overwriting configuration changes made by the user where desirable).
  This allows using the same code to create the initial configuration and upgrade configurations on upgrades.

* If it is unavoidable to run different code during the initial installation, the ``sysconfig.gluon_version`` variable
  can be checked. This variable is ``nil`` during the initial installation and contains the previously install Gluon
  version otherwise.

Script ordering
---------------

These are some guidelines for the script numbers:

* ``0xx``: Basic ``sysconfig`` setup
* ``1xx``: Basic system setup (including basic network configuration)
* ``2xx``: Wireless setup
* ``3xx``: Advanced network and system setup
* ``4xx``: Extended network and system setup (e.g. mesh VPN and next-node)
* ``5xx``: Miscellaneous (everything not fitting into any other category)
* ``6xx`` .. ``8xx``: Currently unused
* ``9xx``: Upgrade finalization