|author||brent s <email@example.com>||2017-11-27 00:09:10 -0500|
|committer||brent s <firstname.lastname@example.org>||2017-11-27 00:11:22 -0500|
hooo boy. draft 1 done, now seeking limited peer review.
Diffstat (limited to 'SPEC.txt')
1 files changed, 340 insertions, 0 deletions
diff --git a/SPEC.txt b/SPEC.txt
new file mode 100644
@@ -0,0 +1,340 @@
+Universal Release Specification
+1. CONVENTIONS IN THIS DOCUMENT
+There are certain conventions used in this document that are used to reference
+various components and attributes of URS ("Universal Release Specification").
+UPSTREAM: The author of software (typically the ones implementing URS).
+DOWNSTREAM: The software packager, user, etc. of software that UPSTREAM creates.
+MUST or REQUIRED: The element, attribute, etc. is *required* to be considered as
+ valid URS.
+SHOULD or RECOMMENDED: The element, attribute, etc. is not required, but is
+ *highly recommended* by the author. Typically, this is
+ to ensure good interoperability and/or clean and smooth
+ interoperability with packaging standards various
+ DOWNSTREAM projects have.
+MAY or OPTIONAL: The element, attribute, etc. is not required, and is not
+ explicitly recommended, but may be implemented at UPSTREAM or
+ DOWNSTREAM's discretion.
+SHOULD NOT or UNRECOMMENDED: The element, attribute, etc. is highly advised
+ against, as it may cause confusion, errors, and/or
+ other instabilities, or the feature is not per-spec
+ guaranteed to be available in all implementations
+ of URS.
+MUST NOT or RESTRICTED: The element, attribute, etc. must not, under any
+ circumstances, be implemented in the presented way, lest
+ breakage is certain to occur.
+2. BASIC FORMAT
+The URS uses an RSS+XML-driven approach.
+RSS and XML have provided a proven and time-tested format of serializing
+metadata in a format that:
+* Provides minimal overhead
+* Is flexible and allows for easily adding new features over time as the scheme
+ matures ("future-proof").
+* Is widely accessible - it can be parsed as plaintext both by machine (via a
+ plethora of libraries already in existence) and human eyes (though you may
+ want to use an RSS reader client) - in fact, all proper "podcasts" found
+ today still use RSS+XML.
+* Is widely supported - one can easily use existing shared webhosting, or an
+ existing webserver, even an FTP server or NFS server to deploy.
+Because of the above, it was decided that RSS+XML would allow for the widest and
+For an example of a complete and valid URS feed, refer to the samplefeed.xml
+file distributed with this specification.
+An XML declaration header for a feed MUST be included. It MUST include:
+* The version (most likely 1.0)
+* The document encoding (most likely UTF-8)
+e.g. "<?xml version="1.0" encoding="UTF-8"?>"
+2.1.2 Root Element
+The root element of the feed MUST be named "rss". It MUST have the "relspec"
+namespace applied (via http://universal-release-specification.com). It SHOULD
+include the XSD as an XSI, to ensure complete processing by clients.
+e.g. <rss xml:lang="en" version="2.0"
+ xsi:schemaLocation="http://universal-release-specification.com/relspec relspec.xsd">
+"Channels" are sections of a feed (section 2.1) that allows DOWNSTREAM to more
+easily track e.g. beta releases vs. stable releases, main projects vs. project
+add-ons, or the like. Specific implementation is at the discretion of UPSTREAM.
+2.2.1 UPSTREAM SHOULD NOT provide multiple separate projects in the same feed.
+2.2.2 UPSTREAM SHOULD use the following order priority for channel listings (if
+multiple channels are used):
+Stable main project releases
+Stable project addon releases (plugins, et. al.)
+Beta main project releases
+Beta project addon releases
+Alpha/development main project releases
+Alpha/development project addon releases
+Translation forks of the above
+Alternate release formats (i.e. .zip, .tar.bz2, .tar.xz, etc.) if different from
+ primary release distribution.
+2.2.3 Channel Elements
+Channel elements MAY be serialized in any order, but channel elements SHOULD be
+presented in the following order:
+* title (REQUIRED)
+* link (REQUIRED)
+* description (REQUIRED)
+* generator (OPTIONAL)
+* managingEditor (REQUIRED)
+* webMaster (REQUIRED)
+* pubDate (REQUIRED)
+* lastBuildDate (RECOMMENDED)
+* category (OPTIONAL)
+* language (RECOMMENDED)
+* copyright (REQUIRED)
+* docs (RECOMMENDED)
+* ttl (OPTIONAL)
+* image (OPTIONAL)
+126.96.36.199 Title Element
+The title of the channel MUST be a human-readable string that will easily
+identify what that channel tracks. It is REQUIRED.
+e.g. <title>FooBar - Stable</title>
+188.8.131.52 Link Element
+The link of the channel MUST be the URL of UPSTREAM project's main website. If
+no website is available, it SHOULD be the URL of any documentation available. It
+If available, it SHOULD use HTTPS.
+184.108.40.206 Description Element
+The description of the project. This summarized description SHOULD NOT exceed
+128 characters. It is REQUIRED.
+e.g. <description>A program that does things.</description>
+220.127.116.11 Generator Element
+The software used to generate/modify/maintain your feed. It SHOULD NOT exceed
+256 characters. It SHOULD include a URL for the generator software, if
+available. It is OPTIONAL.
+e.g. <generator>reladd.py - https://git.square-r00t.net/RelSpec</generator>
+18.104.22.168 ManagingEditor Element
+The managingEditor element is used to specify the author of UPSTREAM, and used
+to contact for problems regarding the software itself. It is REQUIRED.
+e.g. <managingEditor>email@example.com (Some Name)</managingEditor>
+22.214.171.124 WebMaster Element
+The webMaster is the technological contact for the infrastructure *serving*
+UPSTREAM. This is the contact to use if e.g. there is a permissions problem in
+FTP, or the main website is inaccessible, etc. It MAY be the same contact as
+managingEditor. It is REQUIRED.
+e.g. <webMaster>firstname.lastname@example.org (Another Name)</webMaster>
+126.96.36.199 PubDate Element
+The pubDate element contains information on when the content of the feed has
+changed. It MUST be in RFC 822 format. It is REQUIRED.
+e.g. <pubDate>Sat, 25 Nov 2017 20:30:00 GMT</pubDate>
+188.8.131.52 LastBuildDate Element
+The lastBuildDate element indicates when the feed itself was last generated. It
+MUST be in RFC 822 format. It is RECOMMENDED.
+e.g. <lastBuildDate>Sat, 25 Nov 2017 20:30:00 GMT</lastBuildDate>
+184.108.40.206 Category Element
+The category elements act as "keywords". UPSTREAM MAY specify multiple separate
+category elements. They SHOULD describe the function, purpose, etc. of the
+UPSTREAM project. There are currently no canonical categories, but this may be
+implemented in future reveions of this specification. A channel SHOULD NOT
+exceed 5 categories. It is OPTIONAL.
+220.127.116.11 Language Element
+The language element is used as an indication of what language the feed's fields
+(and UPSTREAM's documentation) is written in. It MUST be a value as supported by
+the original RSS 2.0 spec. The lists of valid values can be found at the
+It is RECOMMENDED.
+18.104.22.168 Copyright Element
+The copyright element is used to denote (despite the somewhat misnomer of name)
+the license of an UPSTREAM project. It MUST be one of the SPDX short identifiers
+as found at https://opensource.org/licenses/alphabetical - if the UPSTREAM
+license is not listed in that list, it MUST be "custom" with one exception - if
+UPSTREAM project is under a proprietary license and UPSTREAM author retains all
+rights granted, it MUST be the string "proprietary". It is REQUIRED.
+Note: You may need to review the URL the license links to if a SPDX shorthand
+is not listed next to the name. e.g. as of date of this document's composition,
+the "eCos License version 2.0" license does not have a shorthand listed.
+Clicking on it, however, reveals in the URL "eCos-2.0" - thus, eCos-2.0 would be
+22.214.171.124 Docs Element
+The docs element should be a link to UPSTREAM documentation for the channel's
+project. It is RECOMMENDED.
+126.96.36.199 TTL Element
+The ttl element is a length of time, in seconds, that DOWNSTREAM MAY want to
+cache the feed for. This is useful for projets expecting a great deal of clients
+tracking the feed/channel. It is OPTIONAL.
+188.8.131.52 Image Element
+The image element is used to reference a logo, artwork, etc. representative of
+UPSTREAM. It is RECOMMENDED.
+It contains three sub-elements:
+* title - The title of the artwork (REQUIRED)
+* link - A URI that the artwork should link to (RECOMMENDED)
+* url - The URL of the image so it can be fetched (REQUIRED)
+ <title>FooBar Logo</title>
+"Items" are sections of a Channel (section 2.2) that contain information about a
+2.3.1 UPSTREAM MUST serve newest items at the *top* of a Channel's item
+2.3.2 Item Attributes
+Item attributes MAY be serialized in any order, but item attributes SHOULD be
+presented in the following order:
+* title (REQUIRED)
+* description (OPTIONAL)
+* enclosure (REQUIRED)
+* guid (REQUIRED)
+* author (OPTIONAL)
+* link (RECOMMENDED)
+* comments (RECOMMENDED)
+* relspec:sig (RECOMMENDED)
+* relspec:ver (REQUIRED)
+184.108.40.206 Title Element
+Same as 220.127.116.11, but the name to use for a specific release. The string is at
+UPSTREAM's discretion, but it is RECOMMENDED to use a format including the
+version number of this release. It is REQUIRED.
+e.g. <title>FooBar - Release 1.2.3</title>
+18.104.22.168 Description Element
+Same as 22.214.171.124, but for a specific release. It is RECOMMENDED to include a
+summary or short list of highlights of this specific release. It is OPTIONAL.
+e.g. <description>Fixes security issues, segfaults</description>
+126.96.36.199 Enclosure Element
+Perhaps the most important elements of the entire feed, the enclosure elements
+note where a file for a release can be fetched. Each item MUST include only one
+enclosure. It is REQUIRED.
+It MUST include three attributes: url, length, and type.
+* url - The URL of the release file (e.g. such as a "tarball", zip file, etc.)
+* length - The size of the file found at url, in bytes
+* type - The MIME type of the file found at url
+e.g. <enclosure url="https://foobar.com/releases/1.2.3.tar"
+ type="application/x-tar" />
+188.8.131.52 GUID Element
+The guid element is used to uniquely identify elements in a machine-recognizable
+way. In URS, this MUST be a SHA512 sum of the file found referenced by the
+enclosure (184.108.40.206) element's url attribute (this is to ensure data integrity
+in-transit). It MUST include the isPermaLink="false" attribute. It is REQUIRED.
+e.g. <guid isPermaLink="false">cf83e1357eefb8bdf15428...1a538327af927da3e</guid>
+220.127.116.11 Author Element
+The author element follows the same convention as managingEditor (18.104.22.168), but
+with the allowance of being unique to a release. This MAY be used for UPSTREAMs
+which employ a multi-person release team. See 22.214.171.124 for more information. It
+e.g. <author>email@example.com (Author Name)</author>
+126.96.36.199 Link Element
+The link element contains a URL for full release notes for this release. It is
+188.8.131.52 Comments Element
+The comments element contains a URL for bug reports or other DOWNSTREAM feedback
+as it pertains to this particular release. If a specific release link is not
+available, it MUST be a link to the general bugtracker for UPSTREAM project. If
+this is not available, it MUST be a URL for a page with contact information. It
+184.108.40.206 Relspec:Sig Element
+The relspec:sig element is an extension element that provides a URL to a GnuPG
+or PGP detached-signature file (RFC 4880 § 7). It MAY be in either binary or
+ASCII-armored format (RFC 4880 § 6.2). It MUST NOT be a "clearsign"/"cleartext"
+signature. (RFC 4880 § 7).
+If the author (220.127.116.11) element is specified, this signature MUST at
+least contain a signature from that email address. If it is not specified, this
+signature file MUST at least contain a signature from the managingEditor
+(18.104.22.168) element. It is RECOMMENDED.
+22.214.171.124 Relspec:Ver Element
+The relspec:ver element MUST be a string containing only the version number. It
+MUST be in Semantic Version (https://semver.org/) format. If the UPSTREAM itself
+does not follow Semantic Version versioning schema, it is the UPSTREAM's
+responsibility to convert their native versioning to a Semantic Versioning
+compatible format for the feed to aid packagers. It is REQUIRED.
+e.g. <relspec:ver>1.2.3</relspec:ver> \ No newline at end of file