D 2014-12-14T02:43:15.025
L releases.json
N text/x-markdown
P ab30b7bbe950c54c998c7a83f6db53f372e31099
U mario
W 7103
The most coherent way to [autoupdate](wiki/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](wiki/freshcode).
* The `download:` field can be absent if your project listing already contained a [$versioned](wiki/$version+placeholder) 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](wiki/freshcode) are:
* All releases must include a `version:`, `state:`, `scope:` and `changes:`.
* Additionally <b>`published:` is required</b> 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](wiki/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](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`. <br>(Use pattern and idea originated in: [PUMA Repository](http://freshcode.club/projects/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](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](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.
Z 738dbbbf5a486ee46f94771688b75beb