How to host & release module packages

For easy maintenance and distribution a2 has GitHub as a featured module package hosting platform.
There are other means to offer them but with GitHub it's really most convenient. So far there is:

• via GitHub
• by any URL
• by filesystem
• local
• GitLab? (could just work the same GitHub way)
• Gist?

So kicking off an update for a GitHub hosted package is as easy as:

• edit package meta data and bump semantic version as latest
• commit updated code and a2modsource.json.
• create release on github.com-page for the package with same version as tag.

That's ... yeah that's actually it already! People can now press Check for Updates and be up-to-date.
With a little tooling "any URL"- or network-filesystem-hosting could be just as easy but so far there was nothing polished and it's a little manual labor.

How does it work?

Like described in Module Packages a "module" in a2 is eventually a directory (with a a2module.json) in a package directory (with a a2modsource.json) under the a2 data dir. Now this package config file can contain an update_url that points to some repository to find released and updates.
If there is no such attribute in the config or empty it's considered local and there is no update functionality.

For the initial download and updates a2 looks for a a2modsource.json at the update_url. Generally it's:

• build url from update_url + 'a2modsource.json'
• try fetching data
• get version
• build payload url from update_url + version + .zip
• download
• backup (if updating)
• unpack to local target directory

considerations ...

• Keep the version attribute in masters a2modsource.json as it is at first

• Gather your news info ...

• The update checker in the a2 ui always looks in to the a2modsource.json of a given update_url

• in the case of GitHub the URL is bent to the raw-repository from

  • https://github.com/owner/reponame to
  • https://raw.githubusercontent.com/owner/reponame/master
    so it can also directly load the contents into json. Just as if you had the update_url pointing directly to the location of to a2modsource.json

That means that the version attribute in the master branches a2modsource.json directly points to a release considered as "latest".
This has the advantage that we could make it point to any release which does not have to be the "latest" one but it can also go wrong in different ways:

• You run the dev-version of the module, update the version attribute locally and press Check for Updates: It would backup your version and install the old version
• You check-in the updated a2modsource.json but did not yet create a release: Check for Updates would tell you there is news but there is nothing yet!
• You create a release and did not update the a2modsource.json: GitHub would pack the outdated a2modsource.json into the tagged zip for this release and it would always be outdated. And this is super bad! Needs to be avoided!

So in this scheme we cannot avoid the 2nd scenario, we just need to keep the time frame as small as possible.