Downloads Brainstorming

(Difference between revisions)

Jump to: navigation, search
m
Current revision (21:20, 12 December 2013) (view source)
(move sparkle/appcast stuff together in adjacent subsections near the bottom, update header, authorship from history)
 
(7 intermediate revisions not shown.)
Line 1: Line 1:
-
<h1>Downloads Brainstorming </h1>
+
<entry-title>Downloads Brainstorming </entry-title>
-
The purpose of this page is to capture software download and software update practices in the wild, as one effort to codify practices currently used in the automatic update system called Sparkle.
+
This page is part of the effort to develop a microformat for [[downloads]].
-
This page was recently merged from appcast-brainstorming, and may therefore still have references to an "appcast microformat".
+
See previous research:
-
 
+
* [[downloads-examples]]
-
__TOC__
+
* [[downloads-formats]]
-
 
+
-
== Authors ==
+
-
 
+
-
* [[User:DenisDefreyne|Denis Defreyne]]
+
-
* [http://factoryjoe.com/ Chris Messina]
+
== Context ==
== Context ==
Line 23: Line 18:
* [[hash-brainstorming]] has a section about hAtom integration. The example uses a "download" class, which contains a rel-enclosure link as well as a span with "md5" and "checksum" classes.
* [[hash-brainstorming]] has a section about hAtom integration. The example uses a "download" class, which contains a rel-enclosure link as well as a span with "md5" and "checksum" classes.
-
 
-
== Sparkle-specific Appcast enhancements ==
 
-
 
-
Sparkle adds a few extra features to appcasts:
 
-
 
-
* External release notes URL: used when the release notes are not included in the appcast itself
 
-
* MD5 sums and DSA signatures: used for some extra security
 
-
* Version strings: Sparkle will try to determine the application version from the enclosure name, which is assumed to be APPNAME_VERSION.zip. If this is not possible, the <code>sparkle:version</code> attribute will be used. The <code>sparkle:shortVersionString</code> attribute contains the version string that will be displayed to the user (useful when the actual version number is an internal build number, for example).
 
-
 
-
The downloads microformat should probably support these features as well.
 
-
 
-
The MD5 sum and DSA signature is specific for an enclosure. It is, however, not possible to add these extra attributes to a [[rel-enclosure]] link. A hentry in an downloads microformat can only have one enclosure, so the MD5 sum and DSA signature should be part of the hentry.
 
== Proposal ==
== Proposal ==
Line 88: Line 71:
It's been suggested that tags could be used to mark up OSes and architectures.
It's been suggested that tags could be used to mark up OSes and architectures.
 +
== Issues ==
== Issues ==
Line 105: Line 89:
* Marking up a single download with hAtom doesn't make much sense.
* Marking up a single download with hAtom doesn't make much sense.
-
A simpler download microformat, which is basically a rel-enclosure with some extra data (MD5 sum, DSA signature) may be useful.
+
A simpler download microformat, which is basically a rel-enclosure with some extra data (MD5 sum, DSA signature) may be useful. Something along these lines, perhaps:
 +
 
 +
* download
 +
** [[rel-enclosure]]
 +
** hash (see [[hash-brainstorming]])
 +
** signature
 +
 
 +
For example:
 +
 
 +
<code><pre><p class="download">
 +
    Download <a href="blah.zip" rel="enclosure">Blah 2.1</a>!
 +
    (<span class="checksum"><span class="type">MD5</span> checksum: <span class="value">c23316cb51ca5125d1417faba5cef51e</span></span>).
 +
</p></pre></code>
 +
 
 +
This smaller download microformat could then be used inside a hentry in the larger appcast microformat.
=== Naming ===
=== Naming ===
Line 120: Line 118:
In the proposal above, the "version" class name is used, but I'm not happy about it. In other microformats, "version" is used to indicate the version of the microformat, not the version of something that is described using the microformat. "revision" is probably a better name.
In the proposal above, the "version" class name is used, but I'm not happy about it. In other microformats, "version" is used to indicate the version of the microformat, not the version of something that is described using the microformat. "revision" is probably a better name.
 +
 +
Sparkle can actually use a "shortVersionNumber" argument, which is displayed in Sparkle instead of "version" if present.
 +
 +
These two version attributes will need to be marked up in some way in the appcast microformat at well. Some possible names:
 +
* "revision" and "short-revision"
 +
** The term "revision" isn't usually used in released software; I think I've only heard the term in VCSes (CVS, SVN, etc).
 +
* "app-version" and "app-version-short"
 +
* "enclosure-version" and "short-enclosure-version"
 +
** Seems to refer to the version of the download, and not necessarily the version of the application included in the download
=== Overlap with Changesets ===
=== Overlap with Changesets ===
Changesets are very similar to downloads, with the exception that there are no downloads (another reason why the "downloads" name sucks?). Each changeset entry (hentry) usually has a short description (entry-title), a list of changes (entry-description), and a revision number.
Changesets are very similar to downloads, with the exception that there are no downloads (another reason why the "downloads" name sucks?). Each changeset entry (hentry) usually has a short description (entry-title), a list of changes (entry-description), and a revision number.
 +
 +
=== Download Link in entry-content ===
 +
 +
It makes sense for the download link (the one with rel-enclosure) to sit inside the entry-content. Otherwise, what's the point of having a download link if it doesn't show up in the feed?
 +
 +
If the download link is inside the entry-content, though, Sparkle's "release notes" view will show that download link as well. This is confusing, because people could click that link in the release notes view, which would download the update in Safari like a regular file. Instead, the user should click the "Install Update" button.
 +
 +
Additionally, stuff such as MD5 checksums and DSA signatures should probably be hidden from the release notes view as well, because they can't be used by the user anyway (but they are used by Sparkle).
 +
** MD5s are used manually, i.e. on some download pages they appear as visible text next to the download link, and there are tools (MD5 apps and download apps with MD5 options) for manual copying and pasting
 +
 +
To prevent this download link (as well as the MD5 sum etc) from showing up, anything inside a mini "download" microformat (see above) could be hidden.
 +
** MD5s should not be hidden from users who would copy and paste it (see above)
== To Do ==
== To Do ==
Line 131: Line 150:
* Figure out whether [[hListing]] could be used instead of [[hAtom]].
* Figure out whether [[hListing]] could be used instead of [[hAtom]].
* Figure out whether changesets can benefit from this microformat.
* Figure out whether changesets can benefit from this microformat.
 +
 +
== Appcast history ==
 +
This page was merged from [[appcast-brainstorming]], and may therefore still have references to an "appcast microformat".
 +
 +
The purpose of that page was to capture software download and software update practices in the wild, as one effort to codify practices currently used in the automatic update system called Sparkle.
 +
 +
== Sparkle-specific Appcast enhancements ==
 +
 +
Sparkle adds a few extra features to appcasts:
 +
 +
* External release notes URL: used when the release notes are not included in the appcast itself
 +
* MD5 sums and DSA signatures: used for some extra security
 +
* Version strings: Sparkle will try to determine the application version from the enclosure name, which is assumed to be APPNAME_VERSION.zip. If this is not possible, the <code>sparkle:version</code> attribute will be used. The <code>sparkle:shortVersionString</code> attribute contains the version string that will be displayed to the user (useful when the actual version number is an internal build number, for example).
 +
 +
The downloads microformat should probably support these features as well.
 +
 +
The MD5 sum and DSA signature is specific for an enclosure. It is, however, not possible to add these extra attributes to a [[rel-enclosure]] link. A hentry in an downloads microformat can only have one enclosure, so the MD5 sum and DSA signature should be part of the hentry.
== Software using appcasts ==
== Software using appcasts ==
Line 139: Line 175:
* [http://metaquark.de/appfresh/ AppFresh] uses Sparkle-enhanced appcasts, including those generated by [http://iusethis.com/ iusethis] (e.g. [http://osx.iusethis.com/appcast/igtd the iGTD appcast]).
* [http://metaquark.de/appfresh/ AppFresh] uses Sparkle-enhanced appcasts, including those generated by [http://iusethis.com/ iusethis] (e.g. [http://osx.iusethis.com/appcast/igtd the iGTD appcast]).
* [http://hohle.net/projects/spangle/ Spangle] (formerly known as Perrier) uses Sparkle-enhanced RSS appcasts.
* [http://hohle.net/projects/spangle/ Spangle] (formerly known as Perrier) uses Sparkle-enhanced RSS appcasts.
 +
* [http://www.wakoopa.com Wakoopa]'s [http://www.wakoopa.com/vendors vendor program] (web application) supports VersionTracker [http://en.wikipedia.org/wiki/VersionTracker], Appcast and PAD [http://en.wikipedia.org/wiki/Portable_Application_Description]
== Implementations ==
== Implementations ==

Current revision


This page is part of the effort to develop a microformat for downloads.

See previous research:

Contents

Context

Sites like iusethis.com, versiontracker.com, macupdate.com and download.com, among others, provide software downloads, both new releases and updates.

Among common data in a software update changelog are changes or fixes, completed bugs, new features or modified behavior, and known issues. A version number is also typically supplied, but takes on many forms and is not always numeric.

Lastly, this work should be seen as compatible with hAtom, possibly as a prelude to a format that could be embedded as the payload of an hfeed object.

Related Work

Proposal

This proposal is mostly inspired by appcasts with Sparkle extensions.

Example:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
	<head>
		<title>Version History</title>
	</head>
	<body>
		<h1>Version History</h1>
		<div class="hentry">
			<h2 class="entry-title">Adium <span class="version">1.0.4</span></h2>
			<p>Updated on <abbr class="updated" title="2007-06-20T18:00+01:00">24 June</abbr>.</p>
			<div class="entry-content">
				<ul>
					<li>Fixed a crash introduced in 1.0.3 which could occur when accounts disconnected or status changed</li>
					<li>Fixed group chat when message history is enabled</li>
				</ul>
			</div>

			<p>
				<a href="http://adiumx.cachefly.net/Adium_1.0.4.dmg" rel="enclosure">Download</a>.
				<span class="checksum">
					The <span class="type">MD5</span> checksum of this download is
					<span class="value">e0d123e5f316bef78bfdf5a008837577</span>.
				</span>.
			</p>
		</div>
	</body>
</html>

The hash microformat used in this proposal is likely to change.

Multi-app/arch/OS/... download pages

A single downloads page can have downloads for different applications, different versions, different architectures, different operating systems, etc (for example, the MySQL downloads page).

Here's a probably incomplete list of different download properties:

However, multi-* download pages are hard to do right, and therefore probably not worth supporting. A single HTML page should therefore only contain downloads for one application, one OS, one architecture, etc.

It's been suggested that tags could be used to mark up OSes and architectures.

Issues

Signatures

How should DSA signatures be handled? Should a simple <span class="dsa-signature">...</span> work? Should DSA signatures be part of the hash microformat (see hash-brainstorming)?

Smaller Download Microformat

Merging the appcast and the downloads microformat might not have been a smart idea, for the following reasons:

A simpler download microformat, which is basically a rel-enclosure with some extra data (MD5 sum, DSA signature) may be useful. Something along these lines, perhaps:

For example:

<p class="download">
    Download <a href="blah.zip" rel="enclosure">Blah 2.1</a>!
    (<span class="checksum"><span class="type">MD5</span> checksum: <span class="value">c23316cb51ca5125d1417faba5cef51e</span></span>).
</p>

This smaller download microformat could then be used inside a hentry in the larger appcast microformat.

Naming

What name should this microformat have?

Version Numbers

Each entry needs a version number, so software update frameworks can figure out which version number to display. (Sparkle can actually figure out the version number from the download URL, but not always.)

In the proposal above, the "version" class name is used, but I'm not happy about it. In other microformats, "version" is used to indicate the version of the microformat, not the version of something that is described using the microformat. "revision" is probably a better name.

Sparkle can actually use a "shortVersionNumber" argument, which is displayed in Sparkle instead of "version" if present.

These two version attributes will need to be marked up in some way in the appcast microformat at well. Some possible names:

Overlap with Changesets

Changesets are very similar to downloads, with the exception that there are no downloads (another reason why the "downloads" name sucks?). Each changeset entry (hentry) usually has a short description (entry-title), a list of changes (entry-description), and a revision number.

Download Link in entry-content

It makes sense for the download link (the one with rel-enclosure) to sit inside the entry-content. Otherwise, what's the point of having a download link if it doesn't show up in the feed?

If the download link is inside the entry-content, though, Sparkle's "release notes" view will show that download link as well. This is confusing, because people could click that link in the release notes view, which would download the update in Safari like a regular file. Instead, the user should click the "Install Update" button.

Additionally, stuff such as MD5 checksums and DSA signatures should probably be hidden from the release notes view as well, because they can't be used by the user anyway (but they are used by Sparkle).

To prevent this download link (as well as the MD5 sum etc) from showing up, anything inside a mini "download" microformat (see above) could be hidden.

To Do

Appcast history

This page was merged from appcast-brainstorming, and may therefore still have references to an "appcast microformat".

The purpose of that page was to capture software download and software update practices in the wild, as one effort to codify practices currently used in the automatic update system called Sparkle.

Sparkle-specific Appcast enhancements

Sparkle adds a few extra features to appcasts:

The downloads microformat should probably support these features as well.

The MD5 sum and DSA signature is specific for an enclosure. It is, however, not possible to add these extra attributes to a rel-enclosure link. A hentry in an downloads microformat can only have one enclosure, so the MD5 sum and DSA signature should be part of the hentry.

Software using appcasts

This is a list of programs and frameworks that use appcasts or appcast-like data.

Implementations

The hatom-sparkle project on Google Code (project page, repository) is a fork of Sparkle that adds hAtom support. It is functional, but lacks support for shortVersionString as well as MD5 sums and DSA signatures.

Related Pages

See Also

Downloads Brainstorming was last modified: Thursday, December 12th, 2013

Views