summaryrefslogtreecommitdiff
path: root/SPEC.txt
diff options
context:
space:
mode:
authorbrent s <r00t@square-r00t.net>2017-11-27 00:09:10 -0500
committerbrent s <r00t@square-r00t.net>2017-11-27 00:11:22 -0500
commit5e3c551317dc7715756f8296d9943f2681681501 (patch)
tree8f557203239df0d7772a5b9557d5cc8f0169d2c8 /SPEC.txt
parentbd83b918bcd53ddc997ef849d8af91963dcd0043 (diff)
downloadRelSpec-5e3c551317dc7715756f8296d9943f2681681501.tar.xz
hooo boy. draft 1 done, now seeking limited peer review.
Diffstat (limited to 'SPEC.txt')
-rw-r--r--SPEC.txt340
1 files changed, 340 insertions, 0 deletions
diff --git a/SPEC.txt b/SPEC.txt
new file mode 100644
index 0000000..3c9d78e
--- /dev/null
+++ b/SPEC.txt
@@ -0,0 +1,340 @@
+Universal Release Specification
+v 0.01
+ALPHA RELEASE
+
+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
+easiest adoption.
+
+For an example of a complete and valid URS feed, refer to the samplefeed.xml
+file distributed with this specification.
+
+
+2.1 Feed
+2.1.1 Declaration
+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"
+ xmlns:relspec="http://universal-release-specification.com"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://universal-release-specification.com/relspec relspec.xsd">
+
+
+2.2 Channels
+"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)
+
+2.2.3.1 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>
+
+2.2.3.2 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
+is REQUIRED.
+
+If available, it SHOULD use HTTPS.
+
+e.g. <link>https://foobar.com/</link>
+
+2.2.3.3 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>
+
+2.2.3.4 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>
+
+2.2.3.5 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>somename@somedomain.tld (Some Name)</managingEditor>
+
+2.2.3.6 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>anothername@somedomain.tld (Another Name)</webMaster>
+
+2.2.3.7 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>
+
+2.2.3.8 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>
+
+2.2.3.9 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.
+
+e.g. <category>security</category>
+ <category>security/encryption</category>
+
+2.2.3.10 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
+following URLs:
+
+* http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
+* http://backend.userland.com/stories/storyReader$16
+
+It is RECOMMENDED.
+
+e.g. <language>en-us</language>
+
+2.2.3.11 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.
+
+e.g. <copyright>AGPL-3.0</copyright>
+
+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
+used.
+
+2.2.3.12 Docs Element
+The docs element should be a link to UPSTREAM documentation for the channel's
+project. It is RECOMMENDED.
+
+e.g. <docs>https://foobar.com/documentation/</docs>
+
+2.2.3.13 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.
+
+e.g. <ttl>86400</ttl>
+
+2.2.3.14 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)
+
+e.g. <image>
+ <title>FooBar Logo</title>
+ <link>https://foobar.com/</link>
+ <url>https://foobar.com/media/logo.png</url>
+ </image>
+
+2.3 Items
+"Items" are sections of a Channel (section 2.2) that contain information about a
+specific release.
+
+2.3.1 UPSTREAM MUST serve newest items at the *top* of a Channel's item
+listing.
+
+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)
+
+2.3.2.1 Title Element
+Same as 2.2.3.1, 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>
+
+2.3.2.2 Description Element
+Same as 2.2.3.3, 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>
+
+2.3.2.3 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"
+ length="5242880"
+ type="application/x-tar" />
+
+2.3.2.4 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 (2.3.2.3) 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>
+
+2.3.2.5 Author Element
+The author element follows the same convention as managingEditor (2.2.3.5), but
+with the allowance of being unique to a release. This MAY be used for UPSTREAMs
+which employ a multi-person release team. See 2.3.2.8 for more information. It
+is OPTIONAL.
+
+e.g. <author>authorname@foobar.com (Author Name)</author>
+
+2.3.2.6 Link Element
+The link element contains a URL for full release notes for this release. It is
+RECOMMENDED.
+
+e.g. <link>https://foobar.com/releasenotes/1.2.3</link>
+
+2.3.2.7 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
+is RECOMMENDED.
+
+e.g. <comments>https://bugs.foobar.com/?project=foobar&ver=1.2.3</comments>
+
+2.3.2.8 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 (2.3.2.5) 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
+(2.2.3.5) element. It is RECOMMENDED.
+
+e.g. <relspec:sig>https://foobar.com/releases/1.2.3.tar.sig</relspec:sig>
+
+2.3.2.9 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