From 4c8866ffb7ce2ea6b544c2ac773f26d30f29f528 Mon Sep 17 00:00:00 2001
From: Matthias Schiffer <mschiffer@universe-factory.net>
Date: Fri, 23 Jan 2015 03:29:37 +0100
Subject: [PATCH] Documentation and helper script for the new upgrade script
 handling

---
 contrib/lsupgrade.sh | 44 ++++++++++++++++++++++++++++++++++++++++++++
 docs/dev/upgrade.rst | 43 +++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst       |  1 +
 3 files changed, 88 insertions(+)
 create mode 100755 contrib/lsupgrade.sh
 create mode 100644 docs/dev/upgrade.rst

diff --git a/contrib/lsupgrade.sh b/contrib/lsupgrade.sh
new file mode 100755
index 00000000..ecf2f512
--- /dev/null
+++ b/contrib/lsupgrade.sh
@@ -0,0 +1,44 @@
+#!/bin/bash
+
+# Script to list all upgrade scripts in a clear manner
+# Limitations:
+#  * Does only show scripts of packages whose `files' directory represent the whole image filesystem (which are all Gluon packages)
+
+
+SUFFIX=files/lib/gluon/upgrade
+
+
+shopt -s nullglob
+
+
+if tty -s <&1; then
+	RED="$(echo -e '\x1b[01;31m')"
+	GREEN="$(echo -e '\x1b[01;32m')"
+	BLUE="$(echo -e '\x1b[01;34m')"
+	RESET="$(echo -e '\x1b[0m')"
+else
+	RED=
+	GREEN=
+	BLUE=
+	RESET=
+fi
+
+
+pushd "$(dirname "$0")/.." >/dev/null
+
+find packages -name Makefile | while read makefile; do
+	dir="$(dirname "$makefile")"
+
+	pushd "$dir" >/dev/null
+
+	repo="$(dirname "$dir" | cut -d/ -f 2)"
+	dirname="$(dirname "$dir" | cut -d/ -f 3-)"
+	package="$(basename "$dir")"
+
+	for file in "${SUFFIX}"/*; do
+		echo "${GREEN}$(basename "${file}")${RESET}" "(${BLUE}${repo}${RESET}/${dirname}/${RED}${package}${RESET}/${SUFFIX})"
+	done
+	popd >/dev/null
+done | sort
+
+popd >/dev/null
diff --git a/docs/dev/upgrade.rst b/docs/dev/upgrade.rst
new file mode 100644
index 00000000..3cd57950
--- /dev/null
+++ b/docs/dev/upgrade.rst
@@ -0,0 +1,43 @@
+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.
+
+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 LuCi and 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 achive 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 in ``nil`` during the initial installation and contains the previously install Gluon
+  version otherwise. The package ``gluon-legacy`` (which is responsible for upgrades from the old firmwares of
+  Hamburg/Kiel/Lübeck) uses the special value ``legacy``; other packages should handle this value just as any other
+  string.
+
+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
diff --git a/docs/index.rst b/docs/index.rst
index 9ca1862c..7c3d1c6f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -36,6 +36,7 @@ Developer Documentation
 
    dev/basics
    dev/hardware
+   dev/upgrade
    dev/configmode
 
 Supported Devices