update-walker: add a minimal description

pkgs/build-support/upstream-updater/update-walker.txt

@@ -0,0 +1,118 @@
+update-walker is an imperative semiautomated update helper.
+
+It runs the X.upstream file to find the freshest version of the package in
+the specified upstream source and updates the corresponding X.nix file.
+
+
+
+The simplest available commands:
+
+url: set the upstream source list URL equal to $1; the default is
+meta.downloadPage with meta.homepage fallback
+
+dl_url_re: set the regular expression used to select download links to $1; the
+default is meta.downloadURLRegexp or '[.]tar[.]([^./])+\$' if it is not set
+
+target: specify target expression; default is to replace .upstream extension
+with .nix extension
+
+name: specify the derivation name; default is the basename of the dirname
+of the .upstream file
+
+attribute_name: specify the attribute name to evaluate for getting the current
+version from meta.version; default is to use the derivation name
+
+minimize_overwrite: set config options that mean that only version= and
+sha256= have to be replaced; the default is to regenerate a full upstream
+description block with url, name, version, hash etc.
+
+
+
+A lot of packages can be updated in a pseudo-declarative style using only
+the commands from the previous paragraph.
+
+Some packages do not need any non-default settings, in these case just setting
+meta.updateWalker to true is enough, you can run update-walker directly on the
+.nix file afterwards. In this case minimize_overwrite it implied unless
+meta.fullRegenerate is set.
+
+
+
+The packages that require more fine-grained control than the described options
+allow, you need to take into account the default control flow of the tool.
+
+First, the definitions from update-walker script and additional definitions
+from update-walker-service-specific.sh are loaded. Then the config is executed
+as a shell script. Some of the commands it can use do remember whether they
+have been used. Afterwards the following steps happen: 
+
+attribute_name is set to name unless it has been already set
+
+meta.version is read from the NixPkgs package called attribute_name
+
+download URL regexp is set to default unless it has been already set in the
+updater script
+
+the download page URL gets set to default value unless it has been set
+previously
+
+if the action of getting the download page and choosing the freshest link by
+version has not yet been taken, it happens
+
+if the version has not yet been extracted from the URL, it gets extracted
+
+target nix expression to update gets set to the default value unless it has
+been set explicitly
+
+if the URL version is fresher than the packaged version, the new file gets
+downloaded and its hash is calculated
+
+do_overwrite function is called; the default calculates a big upstream data
+block and puts it after the '# Generated upstream information' marker (the
+marker can be changed by the command marker)
+
+
+
+If the update needs some special logic, it is put into the updater script and
+the corresponding steps are skipped because the needed action has already been
+performed. 
+
+For example: 
+
+minimize_overwrite is exactly the same as
+
+do_overwrite() { do_overwrite_just_version; }
+
+redefinition. You can do a more complex do_overwrite redifinition, if needed.
+It can probably use ensure_hash to download the source and calculate the hash
+and set_var_value.
+
+set_var_value alters the $3-th instance of assigning the $1 name in the
+expression to the value $2. $3 defaults to 1. It can modify $4 instead of the
+current target, it can put the value without quotes if $5 is 1.
+
+
+
+Typical steps include:
+
+ensure_choice: download current URL and find the freshest version link on the
+page, it is now the new URL
+
+ensure_hash: download current URL and calculate the source package hash
+
+ensure_version: extract version from the URL
+
+SF_redirect: replace the current URL with a SourceForge.net mirror:// URL
+
+SF_version_dir: assume SourceForge.net layout and choose the freshest
+version-named subdirectory in the file catalog; you can optionally specify $1
+as a directory name regexp (digits and periods will be required after it)
+
+SF_version_tarball: assume SourceForge.net layout and choose the freshest
+tarball download link
+
+version: apply replacement of $1 with $2 (extended regexp format) to extract
+the version from URL
+
+version_link: choose the freshest versioned link, $1 is the regexp of
+acceptable links