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":
    }

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":
       "license": "MITL",
       "tags": "gtk, vala, desktop, multimedia",
       "image":
       "releases": [
          {
             "version": "2.0.1",
             "state": "stable",
             "scope": "minor bugfix",
             "changes": "Fixed new feature: xyzbar, and ..",
             "download":
             "published": "2013-12-22T17:00:00+00:00"
          },
          {
             "version": "2.0.0",
             "state": "stable",
             "scope": "major feature",
             "changes": "Added completely new GUI, etc...",
             "download":
             "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 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
           "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":
           "ignore": [ ".fslckout" ],
           "dependencies": {
              "jquery": "2.1.0",
           },
           "releases": [
              {
                 "version": "1.0.0",
                 "state": "stable",
                 "scope": "security bugfix",
                 "changes": "Release documentation, and such..",
                 "download":
                 "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

  *  uses a somewhat similar format. 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: 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.