wiki:Technical/UpdateChecker

Update Checker

Table of Contents

  1. Update Checker
  2. Algorithm
  3. Metadata in the URL fetched
  4. Why this works
  5. Legacy update checker design

In the new design, each branch will have a separate URL to fetch.

Aegisub 2.1.8 branch will be fetching ​http://updates.aegisub.org/2.1.8 which will describe all possible updates from version 2.1.8 at the time of fetching.

See also JSON schema for a JSON formulation of the file format

The new file format will still be line-based to ease parsing. All human-readable strings in the lines will be encoded using the inline string encoding implemented in string_codec.cpp. This allows us to encode line breaks among other things in the strings. The files are not intended to be read by humans so this won't be a problem. The files may eventually be automatically generated/maintained by some additional software.

The field-separator on the lines will change to a pipe character, as that is better supported by string_codec.cpp. (It's considered a special character in the encoding.) The new line format will be: 

type|revision|tags|url|friendlyname|description
  • type is one of:
    • dev: Unstable release, usually source only, in the branch.
    • branch: Unstable release, usually source only, in a new branch.
    • stable: Stable release in the branch, there will usually be at most one of these.
    • bugfix: Stable upgrade to a newer branch, which contains only bugfixes compared to the current branch.
    • upgrade: Stable upgrade to a newer branch, which contains major new features.
  • revision: SVN revision the new release was built off. A dev or stable type update is only interesting if this SVN revision number is later than the revision the currently running version was built off.
  • tags can be empty or a space (0x20) separated list of:
    • all: Must be the only tag in the field, the same as blank. Only intended for 2.1.8 updates file.
    • source: Source package release.
    • windows: Binary package for Windows 32 bit.
    • win64: Binary package for Windows 64 bit.
    • mac: A 32 bit Intel binary release for Mac OS X.
    • mac-ppc: A PowerPC binary release for Mac OS X.
    • A Mac OS X Universal binary release should have both the mac and mac-ppc tags.
    • linux-ia32: A portable 32 bit Intel Linux binary.
    • Any binary package tag preceded by auto- means it's an auto-updater package for that platform and the URL field points to the auto-update download.
    • The updates file for version 2.1.8 must have exactly one tag on each line, and only supports all, source, windows, mac tags.
  • url: URL (inline string encoded) the user can go to for more information and download locations. Should point to a HTML page.
  • friendlyname: A short user-readable string (inline string encoded) naming the update path, for use in for example a list of possible updates presented to the user.
  • description: A longer user-readable description (inline string encoded) of the highlights of the update. Not intended to be a replacement for a detailed changelog accessible from the url.

Algorithm

The file is downloaded. Each line is parsed and analysed to determine whether it is interesting or not interesting. If at any step it is determined that a line is interesting or not interesting processing stops for the line.

The application has a list of accepted tags, defined at compile time. The list may have auto- prefix tags added at runtime, depending on configuration.

  1. Check type field:
    • upgrade: interesting
    • bugfix: interesting
    • stable: unknown
    • branch: Same as dev.
    • dev: If running version is an unstable build, unknown. If running version is a stable build, not interesting.
  2. Check revision field:
    • Less than or equal to SVN revision of running version: not interesting.
    • Greater than SVN revision of running version: unknown.
  3. Parse tags field into a list of tags for the package:
    • If the list is empty: interesting
    • If any tag on the package list is not in the application accepted tags list: not interesting
    • If all tags on the package list are in the application accepted tags list: interesting
    • Any tags present in the application accepted tags list but not present in the package tags list are ignored.

Metadata in the URL fetched

When fetching the URL for update checking, some metadata are also passed as a HTTP GET query string. Example:

http://updates.aegisub.org/2.1.8?rev=4000&rel=1&os=win60&lang=en-US

The query string is used solely for statistics on number of users of different versions.

The meanings of the different query parameters:

  • rev: SVN revision the user is currently running. (The branch/"user version" is known from the URL path.)
  • rel: 0 if the user is running an unstable version, 1 if running a stable version. (In practice depends on whether FINAL_RELEASE preprocessor define is set during build.)
  • os: A string describing the OS. Possible values:
    • win2k winxp win2k3 win60 win61 windows
    • osx4 osx5 osx6 osx
    • linux freebsd openbsd netbsd solaris aix hpux unix
    • os2 dos unknown
    • Just because a string is possible here doesn't mean Aegisub supports or ever will support that operating system. Several are only included for completeness, "because we can".
  • lang: A string describing the user's OS language. The exact format depends on OS:
    • On Windows 5.x, the string will be in the form x-winXXXX where XXXX is the ​Windows LANGID value for the language, in hexadecimal.
    • On Windows 6 and later, the string will be an ​RFC 4646 language tag such as en-US.
    • On other systems the format is yet undecided, but it should probably be as close to RFC 4646 language tags as possible.
    • If the language couldn't be determined for some reason the value is x-unk.

Why this works

Builds made from a branch that targets a specific stable version number will fetch a URL that depends on that stable version number. The same URL will be used whether the release is stable or not.

Builds from the trunk will always fetch from ​http://updates.aegisub.org/trunk. This file will describe relevant branches into stable targets. For example, when 2.2.0 is branched off to go towards stable, such that trunk can continue radical development fir the next major version, the updates file for trunk will describe a new branch type release at the revision number the branch was made. The reasoning is that if the user is running a trunk revision from before the branch, the user was probably interested in the next stable version. Now, that version has a dedicated branch, which the user may want to switch to instead. Simultaneously, the trunk file can continue describing later unstable releases in the trunk which are also options for the user, if he prefers sticking to pure bleeding-edge versions. The new 2.2.0 branch updates file will however not describe new releases of the trunk unless a new stable release was made in a different branch.

Keeping different branches in different files makes it easy to make sure only relevant update paths are presented to the user without adding excessive logic in the code.

Feature branches can also be described in this way, for example ​http://updates.aegisub.org/audio-display-rewrite can tell when new interesting updates are present for testers of that branch, or when it is merged back into trunk or another branch.

Legacy update checker design

See sub-page Original Design

Last modified 2 years ago Last modified on 02/15/2011 02:58:51 PM