⌈⌋ branch:  freshcode


Update of "releases.json"

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview

Artifact ID: a127ecd6682ffddd7fa96d62fdb217d97b0d5bc5
Page Name:releases.json
Date: 2014-11-08 15:44:38
Original User: mario
Mimetype:text/x-markdown
Parent: 530d57b25dd0b70ef94bd4777fb506025ddd82c7
Content

The most coherent way to autoupdate project listings on freshcode is using a releases.json file. Its Autoupdate URL can point to a project website, download archive, or into version control systems.

Because there isn't an agreed standard for this, this document defines an ad-hoc scheme.

Basic release.json for just one version

Keep a singular release.json and update that together with completing your packaging process. It just needs to list the most basic fields:

{
    "version": "1.2.9",
    "state": "stable",
    "scope": "minor bugfix",
    "changes": "New user interface, better docs, logo was added..",
    "download": "http://arc.example.org/downl/proj-$version.txz"
}

All but the version: field are optional.

  • Yet if you don't populate the changes: field with a user-friendly summary of the new release, it will only create a hidden release on freshcode.
  • The download: field can be absent if your project listing already contained a $versioned download URL.
  • While scope: is free-form, using any but the common tokens (minor, major, bugfix, feature, security, documentation, cleanup) may result in inoptimal search listings.

Nested releases.json for project history

Alternatively a nested format can contain the complete history of project releases. It lists general project description and adds a releases: [] array for published versions:

{
   "name": "projectid",
   "title": "Awesome App",
   "description": "Is a new desktop thingy for this and that...",
   "homepage": "http://example.org/",
   "license": "MITL",
   "tags": "gtk, vala, desktop, multimedia",
   "image": "http://example.org/logo.png",
   "releases": [
      {
         "version": "2.0.1",
         "state": "stable",
         "scope": "minor bugfix",
         "changes": "Fixed new feature: xyzbar, and ..",
         "download": "http://example.org/downl/proj-2.0.1.txz",
         "published": "2013-12-22T17:00:00+00:00"
      },
      {
         "version": "2.0.0",
         "state": "stable",
         "scope": "major feature",
         "changes": "Added completely new GUI, etc...",
         "download": "http://example.org/downl/proj-2.0.0.txz",
         "published": "2014-05-17T22:50:00+00:00"
      }
   ]
}

It's advisable to list all fields, as this is intended as exchange format.
Special considerations for freshcode are:

  • All releases must include a version:, state:, scope: and changes:.
  • Additionally published: is required and must contain a valid ISO date/time string.
  • The download: field again is optional, but advisable. The $version placeholders should be avoided for reusability with other tracking systems.
  • freshcodes Autoupdate module will only publish the newest version, but may import other entries as hidden releases.

For an autogenerated example see http://freshcode.club/feed/linux. The freshcode.club release export feeds pretty much use the same scheme.

This scheme is in particular sensible for branching and package repository feeds. In particular the state field can be used for branches. Or the version repurposed for package+version entries. For instance a language-aggregator might publish entries as pycrmpkg 1.1 in a name=pypi releases.json feed.

Reusing package.json / composer.json / bower.json

This ad-hoc feed format shares some properties (name, title, version) with established JSON package description schemes. Combining them is therefore an option.

  • Adding a "changes:" entry often suffices.

    {
       "name": "project-name",
       "description": "Package for things and stuff.",
       "author": "maintainer <admin@example.com>",
       "dependencies": {
          "web": ">= 2.0",
    
       },
       "version": "7.2.5",
       "changes": "User-friendly changelog goes here ..."
    }
    

    Which doesn't conflict with the basic dependency items.

  • Introducing a "releases": list is often compatible too:

    {
       "name": "project-id",
       "version": "1.0.0",
       "main": "path/to/main.css",
       "ignore": [ ".fslckout" ],
       "dependencies": {
          "jquery": "2.1.0",
       },
       "releases": [
          {
             "version": "1.0.0",
             "state": "stable",
             "scope": "security bugfix",
             "changes": "Release documentation, and such..",
             "download": "http://example.org/proj-1.0.0.zip",
             "published": "2014-12-17T22:50:00+00:00"
          }
       ]
    }
    

    This of course duplicates the newest version field as latest release.

Such augmented package.json or bower.json, composer.json thus become drop-in combinations suitable for autoupdates. Caveat: composer specifically is JSON schema constrained (reasoning undocumented), thus coerces wrapping additional attributes under extra:[] (not yet supported).

This page advocates the resource names release.json or releases.json only insofar, as it might benefit autodiscovery for other FLOSS directories/tracking projects.

Similar formats, further research

  • Kernel.org uses a somewhat similar format. https://www.kernel.org/releases.json It would actually suffice as releases.json, uses releases:[] already. The published: date however is wrapped in a released: compound of timestamp and isodate. Atypically it lists multiple branches as moniker:. There's no branch support in freshcode yet (alternatives: just repackage as change scope and/or state). kernel-releases.json omits an end user summary changes: field of course. Yet the changelog: reference (a github log) can be extracted by the AutoupdateRegex module already. So maybe a combinatory regex/releases.json module made sense as well...

  • PyPI provides a more elaborate JSON scheme: http://pypi.python.org/pypi/py-translate/json. It omits a changes: field (all release notes in package pages are hand-crafted). It provides the version as object key within releases:. Within there it doubles source and binary entries however. Interestingly the general project infos include a Trove category list.