summaryrefslogtreecommitdiff
path: root/SPEC.txt
blob: 3c9d78e49d99a35e038a053eb358f342e2f3d748 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
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>