⌈⌋ branch:  freshcode


Update of "releases.json"

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

Overview

Artifact ID: c5cff819414ba1b566bfd4a8fca170f909b5c573
Page Name:releases.json
Date: 2014-12-14 02:43:15
Original User: mario
Mimetype:text/x-markdown
Parent: ab30b7bbe950c54c998c7a83f6db53f372e31099
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.

    • For example you can alternate between "state": "2.4 stable" and releases with "state": "2.5 dev", and then have individual releases concretize the current version/patch numbers.
  • Or the version repurposed for package+version entries.

    • For instance a language-aggregator might publish entries as pycrmpkg 1.1.
      (Use pattern and idea originated in: PUMA Repository.)

Plain changelog updates for example don't have so much control here.

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.