releases.json
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:
andchanges:
. - 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.
- For example you can alternate between
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.)
- For instance a language-aggregator might publish entries as
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
, usesreleases:[]
already. Thepublished:
date however is wrapped in areleased:
compound oftimestamp
andisodate
. Atypically it lists multiple branches asmoniker:
. There's no branch support in freshcode yet (alternatives: just repackage as change scope and/or state). kernel-releases.json omits an end user summarychanges:
field of course. Yet thechangelog:
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 withinreleases:
. Within there it doubles source and binary entries however. Interestingly the general project infos include a Trove category list.