Icon sizes and display densities

[Marcos Caceres]

Hi,
I'm reevaluating the app manifest format as part of the standardization effort at the W3C - trying to generalize it for use on the Web. I have some concerns about how the current manifest format deals with icon sizes and display densities, which I would like to change in the W3C version of the manifest format [1].

Our current manifest format declares icons like this:

"icons": {
"16": "/img/icon_16.png",
"48": "/img/icon_48.png",
"128": "/img/icon_128.png"
}


# Problems, as I see them
Declaring one of the dimensions is redundant (the image has the dimensions built it) and error prone for formats that have an intrinsic size. It also doesn't scale well for usage on high density devices, meaning that redundant data may get downloaded. It also limits the control that developers have over which icons get displayed for which pixel density. Furthermore, the "16", "48", "128" dimensions appear to be FxOS specific (and so is the requirement that icons be square).

# Proposal
I would like to propose we change this to accepting an array of URLs:

"icons": ["/img/small.png", "/img/med.png", "/img/large.png"]

Then the UA can derive the dimensions automatically and decide what icon is best to display for an application based on the available display area.

# Supporting SVG
For formats with non-intrinsic sizes (i.e., SVG), we should allow either a URL or an object:

{src: "icon.svg", width: "...px", height: "...px", density: "1x"}
(where the "density" is the device pixel ratio density)

If svg is included just as a URL, then <svg width/height> can be used, or if the dimensions are missing, SVG can be used for when large icons are needed (i.e., when the raster graphics no longer fit the display area).

#High-density displays
To better support high density icon selection (and potentially save some bandwidth), we could allow for a multiplier using CSS image-set's Nx syntax:

"icons": [
"/img/small.png", "/img/med.png", "/img/large.png",

"/img/small_retina.png 2x", "/img/med_retina.png 2x", "/img/large_retina.png 2x",
"/img/small_shd.png 3x", "/img/med_shd.png 3x", "/img/large_shd.png 3x"
]


When the multiplier is missing 1x is assumed, of course. Then the UA is free to ignore icons with multipliers higher than that of its display density. I don't like having to repeat the multiplier, but would like to avoid overcomplicating the data structure used to represent what is needed to meet the use cases.

#Backwards compat
If the W3C format starts using an array instead of an object, backwards compatibility can be retained with existing FxOS content (if type is object === Mozilla format; if type is array === W3C format). Of course, if we start using the W3C format, we would need to deprecate using an object.

Thoughts?

[1] http://www.w3.org/2012/sysapps/manifest/
--
Marcos Caceres

[Matt Basta]

> If the W3C format starts using an array instead of an object, backwards compatibility can be retained with existing FxOS content (if type is object === Mozilla format; if type is array === W3C format). Of course, if we start using the W3C format, we would need to deprecate using an object.

This isn't backwards compatibility since existing devices that implement the old standard will still break.

There is at least one bug on file (disclaimer: I filed it) for another issue, which is platform-specific icons. The icon guidelines for Windows apps, for instance, are difference from the icon guidelines for Android apps. A developer wishing to tailor his icon to look native on each platform can't do that at the moment.

There is a lot that can be done with icons, but removing information from the manifest in a backwards-incompatible way probably isn't the right way to go.

_______________________________________________
dev-webapps mailing list
dev-w...@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-webapps

[Marcos Caceres]

On Friday, May 10, 2013 at 6:35 PM, Matt Basta wrote:

> > If the W3C format starts using an array instead of an object, backwards compatibility can be retained with existing FxOS content (if type is object === Mozilla format; if type is array === W3C format). Of course, if we start using the W3C format, we would need to deprecate using an object.
>
> This isn't backwards compatibility since existing devices that implement the old standard will still break.

You are correct, my bad. When an array is used, the array is ignored (in which case, the default icon is shown).

<snip - moving platform detection to different thread>

> There is a lot that can be done with icons, but removing information from the manifest in a backwards-incompatible way probably isn't the right way to go.

Right, but I'm still interested in addressing the high density display use cases and dealing with the issues I mentioned. Dealing with icons is quite fiddly at the moment.

[Jonas Sicking]

On Fri, May 10, 2013 at 10:19 AM, Marcos Caceres <mcac...@mozilla.com> wrote:
> Hi,
> I'm reevaluating the app manifest format as part of the standardization effort at the W3C - trying to generalize it for use on the Web. I have some concerns about how the current manifest format deals with icon sizes and display densities, which I would like to change in the W3C version of the manifest format [1].
>
> Our current manifest format declares icons like this:
>
> "icons": {
> "16": "/img/icon_16.png",
> "48": "/img/icon_48.png",
> "128": "/img/icon_128.png"
> }
>
>
> # Problems, as I see them
> Declaring one of the dimensions is redundant (the image has the dimensions built it) and error prone for formats that have an intrinsic size. It also doesn't scale well for usage on high density devices, meaning that redundant data may get downloaded. It also limits the control that developers have over which icons get displayed for which pixel density. Furthermore, the "16", "48", "128" dimensions appear to be FxOS specific (and so is the requirement that icons be square).
>
> # Proposal
> I would like to propose we change this to accepting an array of URLs:
>
> "icons": ["/img/small.png", "/img/med.png", "/img/large.png"]

I'm not overly excited about forcing implementations to download all
images just to see what size they are. Though given that this doesn't
have to be done terribly often, maybe I'm overly sensitive.

> Then the UA can derive the dimensions automatically and decide what icon is best to display for an application based on the available display area.
>
> # Supporting SVG
> For formats with non-intrinsic sizes (i.e., SVG), we should allow either a URL or an object:
>
> {src: "icon.svg", width: "...px", height: "...px", density: "1x"}
> (where the "density" is the device pixel ratio density)

Do we really need densities or width/height? The idea is that it's the
same picture just in different pixel sizes, right? So if it's an SVG
we can just scale it to whatever size we need. And if we have a
high-density display then we can just use the picture with a high
resolution?

I guess there could be an argument for enabling an app to provide a
picture which has fewer details which is more appropriate to use for
really small icons. But the above doesn't seem optimized for that
scenario. At the very least you'd want to express the size in mm
rather than pixels for that.

/ Jonas

[Mounir Lamouri]

On 10/05/13 18:19, Marcos Caceres wrote:
> Hi,
> I'm reevaluating the app manifest format as part of the standardization effort at the W3C - trying to generalize it for use on the Web. I have some concerns about how the current manifest format deals with icon sizes and display densities, which I would like to change in the W3C version of the manifest format [1].
>
> Our current manifest format declares icons like this:
>
> "icons": {
> "16": "/img/icon_16.png",
> "48": "/img/icon_48.png",
> "128": "/img/icon_128.png"
> }
>
>
> # Problems, as I see them
> Declaring one of the dimensions is redundant (the image has the dimensions built it) and error prone for formats that have an intrinsic size. It also doesn't scale well for usage on high density devices, meaning that redundant data may get downloaded. It also limits the control that developers have over which icons get displayed for which pixel density. Furthermore, the "16", "48", "128" dimensions appear to be FxOS specific (and so is the requirement that icons be square).
>
> # Proposal
> I would like to propose we change this to accepting an array of URLs:
>
> "icons": ["/img/small.png", "/img/med.png", "/img/large.png"]
>

> Then the UA can derive the dimensions automatically and decide what icon is best to display for an application based on the available display area.

I like that idea :)

> # Supporting SVG
> For formats with non-intrinsic sizes (i.e., SVG), we should allow either a URL or an object:
>
> {src: "icon.svg", width: "...px", height: "...px", density: "1x"}
> (where the "density" is the device pixel ratio density)
>

> If svg is included just as a URL, then <svg width/height> can be used, or if the dimensions are missing, SVG can be used for when large icons are needed (i.e., when the raster graphics no longer fit the display area).

I join Jonas here: isn't SVG, by definition, able to render at any size
quite nicely? The only issue being the level of detail the image might
have. Shouldn't we have {min,max}-{width,height} instead then? We could
also simply have width/height as a "preferred size" but the heuristic
used to pick the best image might not please the app maybe? or maybe
max-width/max-height are enough to ask the UA to use this icon until a
specific size and another one for bigger sizes? I'm thinking out loud
here but I'm basically not sure width/height is the information we want.

I'm not sure why we need "density" for SVG but I don't know much about
that kind of problems so maybe I'm missing something.

> #High-density displays
> To better support high density icon selection (and potentially save some bandwidth), we could allow for a multiplier using CSS image-set's Nx syntax:
>

> "icons": [

> "/img/small.png", "/img/med.png", "/img/large.png",
>
> "/img/small_retina.png 2x", "/img/med_retina.png 2x", "/img/large_retina.png 2x",
> "/img/small_shd.png 3x", "/img/med_shd.png 3x", "/img/large_shd.png 3x"
> ]
>
> When the multiplier is missing 1x is assumed, of course. Then the UA is free to ignore icons with multipliers higher than that of its display density. I don't like having to repeat the multiplier, but would like to avoid overcomplicating the data structure used to represent what is needed to meet the use cases.

Again, this question might be naïve but if the UA knows that it wants to
show an icon at a specific size, it knows the number of pixels being
needed to render the icon, right? Why do we need this density ration?
Can't the UA simply pick the icon with the most appropriate size?

--
Mounir

[Matt Basta]

Perhaps a good solution (without rewriting the spec) would be to allow a size "*" to be specified which must point at an SVG file. If the platform supports it and the developer has specified a valid SVG file, the platform should prefer the resampled SVG over the PNGs.

This would be backwards-compatible and also allow for the Marketplace to do clever testing to make sure that the developer is doing everything correctly.

[James Hugman]

Hi,

I don't really care for platform specific icons, though I do care that
that we are able to provide don't fall into the same trap that Apple
have fallen into wrt display sizes and densities.

The microparsing of filenames (e.g. icon.png, ic...@2x.png,
ic...@2x-ipad.png) isn't just annoying to implement - it's not really
scalable with the number of display densities and sizes we're likely to
have to support.

I do like Android's device independent pixels (dips), which allows the
dev to put resources in the display density buckets.

The bucketing that Android uses: ldpi, mdpi, hdpi, xhdpi, xxhdpi etc
seems to be a little more granular, but as Google are finding, it's not
granular enough, and they also want to differentiate between different
physical sizes of device.

https://developer.android.com/guide/practices/screens_support.html

The designers I've worked with who're used to the 1x == iPhone, 2x ==
iPhone Retina have discovered and re-discovered the information
contained in this blog post, which also be relevant here:
http://www.teehanlax.com/blog/density-converter/

Many thanks, and regards,

James

[Kumar McMillan]

On May 15, 2013, at 1:12 AM, Jonas Sicking <jo...@sicking.cc> wrote:

> On Fri, May 10, 2013 at 10:19 AM, Marcos Caceres <mcac...@mozilla.com> wrote:
>> Hi,
>> I'm reevaluating the app manifest format as part of the standardization effort at the W3C - trying to generalize it for use on the Web. I have some concerns about how the current manifest format deals with icon sizes and display densities, which I would like to change in the W3C version of the manifest format [1].
>>
>> Our current manifest format declares icons like this:
>>
>> "icons": {
>> "16": "/img/icon_16.png",
>> "48": "/img/icon_48.png",
>> "128": "/img/icon_128.png"
>> }
>>
>>
>> # Problems, as I see them
>> Declaring one of the dimensions is redundant (the image has the dimensions built it) and error prone for formats that have an intrinsic size. It also doesn't scale well for usage on high density devices, meaning that redundant data may get downloaded. It also limits the control that developers have over which icons get displayed for which pixel density. Furthermore, the "16", "48", "128" dimensions appear to be FxOS specific (and so is the requirement that icons be square).
>>
>> # Proposal
>> I would like to propose we change this to accepting an array of URLs:
>>
>> "icons": ["/img/small.png", "/img/med.png", "/img/large.png"]
>

> I'm not overly excited about forcing implementations to download all
> images just to see what size they are. Though given that this doesn't
> have to be done terribly often, maybe I'm overly sensitive.

This was my concern too. It seems unrealistic to require the user agent to download all images just to determine their sizes. There could be some large images in there, like 512 px that a mobile user agent will never use anyway. I'm pretty sure that's why the size hints were added in the first place but I don't know the history of the spec.

>
>> Then the UA can derive the dimensions automatically and decide what icon is best to display for an application based on the available display area.
>>

>> # Supporting SVG
>> For formats with non-intrinsic sizes (i.e., SVG), we should allow either a URL or an object:
>>
>> {src: "icon.svg", width: "...px", height: "...px", density: "1x"}
>> (where the "density" is the device pixel ratio density)
>

> Do we really need densities or width/height? The idea is that it's the
> same picture just in different pixel sizes, right? So if it's an SVG
> we can just scale it to whatever size we need. And if we have a
> high-density display then we can just use the picture with a high
> resolution?
>
> I guess there could be an argument for enabling an app to provide a
> picture which has fewer details which is more appropriate to use for
> really small icons. But the above doesn't seem optimized for that
> scenario. At the very least you'd want to express the size in mm
> rather than pixels for that.
>
> / Jonas

[Marcos Caceres]

On Wednesday, May 15, 2013 at 7:12 AM, Jonas Sicking wrote:

> On Fri, May 10, 2013 at 10:19 AM, Marcos Caceres <mcac...@mozilla.com (mailto:mcac...@mozilla.com)> wrote:
> > Hi,
> > I'm reevaluating the app manifest format as part of the standardization effort at the W3C - trying to generalize it for use on the Web. I have some concerns about how the current manifest format deals with icon sizes and display densities, which I would like to change in the W3C version of the manifest format [1].
> >
> > Our current manifest format declares icons like this:
> >
> > "icons": {
> > "16": "/img/icon_16.png",
> > "48": "/img/icon_48.png",
> > "128": "/img/icon_128.png"
> > }
> >
> >
> > # Problems, as I see them
> > Declaring one of the dimensions is redundant (the image has the dimensions built it) and error prone for formats that have an intrinsic size. It also doesn't scale well for usage on high density devices, meaning that redundant data may get downloaded. It also limits the control that developers have over which icons get displayed for which pixel density. Furthermore, the "16", "48", "128" dimensions appear to be FxOS specific (and so is the requirement that icons be square).
> >
> > # Proposal
> > I would like to propose we change this to accepting an array of URLs:
> >
> > "icons": ["/img/small.png", "/img/med.png", "/img/large.png"]
>
> I'm not overly excited about forcing implementations to download all
> images just to see what size they are. Though given that this doesn't
> have to be done terribly often, maybe I'm overly sensitive.

I think that's a fair concern - and it depends on how this is implemented. Right now, when I install an app from the Firefox store, Firefox desktop browser on Mac is creating an application bundle on my hard drive, and it's converting the icons from the application into an "appicon.icns" file. As there is no way to know a head of time what the screen density of the display of my computer will be, it is appropriate to d/l all the icons (I could d/l this on my MacBook retina, but then plug this into a single density display - scaling the 2x icons on my single density display would be inappropriate because they would blur [1]).

[1] http://bjango.com/articles/designingforretina2/

On mobile devices/platforms, it might be ok to discard low and very high density icons. This is why keying the icons off density might be a solution (so you only download the ones related to the screen). That way, the UA can match on density and ignore the ones that are not right for the device pixel ratio (potentially saving bytes).

icons: [
{src: "foo"},

{src: ["/foo", "/bar"], density: 2},
{src: ["/bar", "/baz", "/mega"], density: 3}
]

The model above also makes icon objects more extensible, in case we need to add more things in the future (e.g., roles). And takes away the pain of keying off size for developers (i.e., "here are my icons! user agent, figure it out!").

But yes, the tradeoff is downloading stuff the UA might not need.

> > Then the UA can derive the dimensions automatically and decide what icon is best to display for an application based on the available display area.
> >
> > # Supporting SVG
> > For formats with non-intrinsic sizes (i.e., SVG), we should allow either a URL or an object:
> >
> > {src: "icon.svg", width: "...px", height: "...px", density: "1x"}
> > (where the "density" is the device pixel ratio density)
>
> Do we really need densities or width/height? The idea is that it's the
> same picture just in different pixel sizes, right?

For SVG, you need a width and height because the SVG file may not have an explicit size. It may also be inappropriate to use on a 1x density device because anti-aliasing would make it illegible/blurry. Sub-pixel anti-aliasing on a 2x or 3x screen would again make this icon suitable for display to a user.

> So if it's an SVG
> we can just scale it to whatever size we need.

Unfortunately, no. SVG only really works for very large icons (anti-aliasing makes a mess at lower resolutions) - [4] states that anything lower than 48px is problematic. Please see the first graphic from [4], which shows the problem clearly. See also [2] (last image), which shows what happens when you scale up!

As stated in [2], and echoed in [1] and [3]:

"It’s simply not possible to create excellent, detailed icons which can be arbitrarily scaled to very small dimensions while preserving clarity. Small icons are caricatures: they exaggerate some features, drop others, and align shapes to a sharp grid. Even if all icons could be executed as vectors, the largest size would never scale down well."

Vector graphic performance is also cited as an issue in both [2] and [3] (though no primary source is given).

Also, tool support for exporting SVG is limited/expensive/crappy so it's unlikely a lot of people will use it. We can probably already gather data on SVG usage for icons from the apps that are already in the FxOS store to see if there are any.

[2] http://mrgan.tumblr.com/post/708404794/ios-app-icon-sizes
[3] http://mobile.smashingmagazine.com/2010/11/17/designing-for-iphone-4-retina-display-techniques-and-workflow/
[4] http://www.firewheeldesign.com/sparkplug/2006/April/icon_design_bitmap_vs_vector.php

> And if we have a
> high-density display then we can just use the picture with a high
> resolution?

Sometimes, yes. Generally, icons of different sizes contain different levels of detail. See, section 3:
http://psd.tutsplus.com/articles/7-principles-of-effective-icon-design/

> I guess there could be an argument for enabling an app to provide a
> picture which has fewer details which is more appropriate to use for
> really small icons.

This is not really an argument. That's standard practice. Open up any app's content on your computer and find the icon set for it - you will see exactly this.

Icons can also contain different details at the same size and for different pixel densities (because you can pack more detail and legibility into a retina icon) - plus they could be "art directed" (though I imagine this is rare - an example of "art direction" would be adding a graphical "HD" stamp for 2x density and up - or simply adding more lines and details because aliasing is not as noticeable).

As stated in [1]:
"iOS needs a full set of 1× and 2× images. If iOS (or Xcode) bitmap scaled your 2× images down, the quality of your assets would be reduced."

Again, you can see good examples and discussion of this in [1].

> But the above doesn't seem optimized for that
> scenario. At the very least you'd want to express the size in mm
> rather than pixels for that.

Under ideal conditions, you are correct; but on screen you can only really design for 2 things:

1. pixels
2. pixel density

And both 1 and 2 vary in size from one display to the next. Tricky things, them pixels :)

[Jonas Sicking]

On Wed, May 15, 2013 at 11:06 AM, Marcos Caceres <mcac...@mozilla.com> wrote:
>> > # Supporting SVG
>> > For formats with non-intrinsic sizes (i.e., SVG), we should allow either a URL or an object:
>> >
>> > {src: "icon.svg", width: "...px", height: "...px", density: "1x"}
>> > (where the "density" is the device pixel ratio density)
>>
>> Do we really need densities or width/height? The idea is that it's the
>> same picture just in different pixel sizes, right?
>
> For SVG, you need a width and height because the SVG file may not have an explicit size. It may also be inappropriate to use on a 1x density device because anti-aliasing would make it illegible/blurry. Sub-pixel anti-aliasing on a 2x or 3x screen would again make this icon suitable for display to a user.
>> So if it's an SVG
>> we can just scale it to whatever size we need.
>
> Unfortunately, no. SVG only really works for very large icons (anti-aliasing makes a mess at lower resolutions) - [4] states that anything lower than 48px is problematic. Please see the first graphic from [4], which shows the problem clearly. See also [2] (last image), which shows what happens when you scale up!
>
> As stated in [2], and echoed in [1] and [3]:
>
> "It’s simply not possible to create excellent, detailed icons which can be arbitrarily scaled to very small dimensions while preserving clarity. Small icons are caricatures: they exaggerate some features, drop others, and align shapes to a sharp grid. Even if all icons could be executed as vectors, the largest size would never scale down well."
>
> Vector graphic performance is also cited as an issue in both [2] and [3] (though no primary source is given).
>
> Also, tool support for exporting SVG is limited/expensive/crappy so it's unlikely a lot of people will use it. We can probably already gather data on SVG usage for icons from the apps that are already in the FxOS store to see if there are any.

It sounds like there are a few separate concerns that we may need to address:

* For SVG icons, provide a minimum size in pixels below which the SVG
icon is not appropriate to use because it will look blurry.
* For SVG icons, possibly provide an exact pixel size which is the
only appropriate pixel size to render the icon.
* For pixel-based image formats, provide width/height in pixels so
that implementation can avoid downloading file if not useful.
* For all icons, provide a minimum size in mm below which the icon is
not appropriate to use due to containing too small details.

I'm not sure that the last one is useful really. Having used a
"retina" display for a while now, I'm not convinced that there is ever
a situation where if the platform wants to render a image at 50x50
retina-pixels where we couldn't use an icon that was authored for
50x50 normal pixels. That goes both for SVG icons or pixel-based
icons.

In other words, I think only providing the appropriate pixel size for
each icon is enough.

But if that's not the case, then it seems to me that providing
information in the form of minimum physical size is more
understandable than in the form of device resolution.

/ Jonas

[Mounir Lamouri]

Hi,

I would like to resurrect this thread with the following proposal:
"icons" will contain an array of objects that will have one mandatory
property named 'href'.

There will be three optional properties: 'width', 'height' and
'density'. 'width' and 'height' will be a number expressing the size of
the icon in pixels and 'density' will for the moment be something in the
following set { "1x", "1.5x", "2x", "3x" }. "1x" will be the default
value if the property is missing or has an invalid value. We might
extend this property to include dpi values.

If the entry doesn't contain a width/height information and the image is
a bitmap image, the UA will have to download the entry to find out its size.

When the entry is a vectorial based image, if it has no size
information, it will be used every time an image with a size not in the
array is requested. If a vectorial based image has some size information
that will be considered as "best viewed as x*y". In which case, it will
be preferred to be scaled to another size but if a bitmap image has a
quite closer size it will not. For example, a bitmap image of 60*60 will
still be preferred compared to a SVG image of 8*8 if we want to show a
64*64 image (the bitmap image will be scaled).

An example:
"icons": [
{ "href": "foo.png" },
{ "href": "bar.png", "height": "16px", "width": "16px" },
{ "href": "bar_2.png", "height": "32px", "width": "32px", "density":
"2x" },
{ "href": "foobar.svg" }
],

How does that look? Vivien and Tim? Would you like to implement that in
Gaia?

Cheers,
--
Mounir

[Marcos Caceres]

On Monday, June 17, 2013 at 5:11 PM, Mounir Lamouri wrote:

> Hi,
>
> I would like to resurrect this thread with the following proposal:
> "icons" will contain an array of objects that will have one mandatory
> property named 'href'.

"Mandatory" here means that if href is missing or not a URL, then it is in error and the object is ignored (and a warning is reported in the error console). Also, maybe "src" might be a more appropriate name for the member as it matches img tag.

> There will be three optional properties: 'width', 'height' and
> 'density'. 'width' and 'height' will be a number expressing the size of
> the icon in pixels and 'density' will for the moment be something in the
> following set { "1x", "1.5x", "2x", "3x" }.

We probably don't need to declare "x", as it's redundant in that the member is "density". If we want to support other types of "density" in the future, we can qualify those. Right now, the semantics of density is "device pixel ratio".

Also, my personal experience with "2x" and "3x" is that it's easy to get wrong, because people are very used to writing "x2" and "x3".

Note that the above also applies for width and height. It should be optional to have to add "px" at the end of a value (i.e., "width": "50" should be equivalent to "50px", but not to "50xp" which is unsupported and hence ignored).

> "1x" will be the default
> value if the property is missing or has an invalid value. We might
> extend this property to include dpi values.

If we do that, we can then support "{number}{dpi | x | etc.}"

> If the entry doesn't contain a width/height information and the image is
> a bitmap image, the UA will have to download the entry to find out its size.

It may ignore 1x entries, if 2x one are available.

> When the entry is a vectorial based image, if it has no size
> information, it will be used every time an image with a size not in the
> array is requested.

There is currently no information that allows one to determine the type of an image.

Options:
1. type member (e.g., "type": "image/svg")
2. head request (expensive - and might not yield anything useful)
3. heuristics, like checking for a file extension (can be unreliable - doesn't help for dynamically generated content or content with no extension… could also download the first few bytes to check the magic number, but it's also expensive)

> If a vectorial based image has some size information
> that will be considered as "best viewed as x*y". In which case, it will
> be preferred to be scaled to another size but if a bitmap image has a
> quite closer size it will not.

> For example, a bitmap image of 60*60 will
> still be preferred compared to a SVG image of 8*8 if we want to show a
> 64*64 image (the bitmap image will be scaled).
>
> An example:
> "icons": [
> { "href": "foo.png" },
> { "href": "bar.png", "height": "16px", "width": "16px" },
> { "href": "bar_2.png", "height": "32px", "width": "32px", "density":
> "2x" },
> { "href": "foobar.svg" }
> ],
>
> How does that look? Vivien and Tim? Would you like to implement that in
> Gaia?
>

--
Marcos Caceres

[Matt Basta]

I don't think this is viable solution since it's not backwards compatible. Older devices won't be able to understand the manifest.

----- Original Message -----
From: "Mounir Lamouri" <mou...@lamouri.fr>

To: "dev-webapps" <dev-w...@lists.mozilla.org>
Cc: "Marcos Caceres" <mcac...@mozilla.com>, "Vivien Nicolas" <vnic...@mozilla.com>, "Jonas Sicking" <jo...@sicking.cc>, "Tim Guan-tin Chien" <timd...@mozilla.com>
Sent: Monday, June 17, 2013 9:11:43 AM
Subject: Re: Icon sizes and display densities

Hi,

I would like to resurrect this thread with the following proposal:
"icons" will contain an array of objects that will have one mandatory
property named 'href'.

There will be three optional properties: 'width', 'height' and
'density'. 'width' and 'height' will be a number expressing the size of
the icon in pixels and 'density' will for the moment be something in the

following set { "1x", "1.5x", "2x", "3x" }. "1x" will be the default

value if the property is missing or has an invalid value. We might
extend this property to include dpi values.

If the entry doesn't contain a width/height information and the image is
a bitmap image, the UA will have to download the entry to find out its size.

When the entry is a vectorial based image, if it has no size
information, it will be used every time an image with a size not in the

array is requested. If a vectorial based image has some size information

that will be considered as "best viewed as x*y". In which case, it will
be preferred to be scaled to another size but if a bitmap image has a
quite closer size it will not. For example, a bitmap image of 60*60 will
still be preferred compared to a SVG image of 8*8 if we want to show a
64*64 image (the bitmap image will be scaled).

An example:
"icons": [
{ "href": "foo.png" },
{ "href": "bar.png", "height": "16px", "width": "16px" },
{ "href": "bar_2.png", "height": "32px", "width": "32px", "density":
"2x" },
{ "href": "foobar.svg" }
],

How does that look? Vivien and Tim? Would you like to implement that in
Gaia?

[Vivien]

I won't be against implementing the support of something that is closer
to srcset in Gaia.

On 17/06/2013 19:01, Matt Basta wrote:
> I don't think this is viable solution since it's not backwards compatible. Older devices won't be able to understand the manif

That's true but this is pretty obvious that some changes will (and
should) happen in the manifest format. Which solutions do you propose in
order to make it evolves ? (I assume you think about that when designing
the manifest format)

[Marcos Caceres]

On Monday, June 17, 2013 at 6:01 PM, Matt Basta wrote:

> I don't think this is viable solution since it's not backwards compatible. Older devices won't be able to understand the manifest.

So, we are probably going to keep hitting this problem going forward, as we are not standardizing just Mozilla's manifest format (we are trying to learn from all available formats to create a solution that is right for the Web). Other W3C members have their own requirements, etc. and they've been quite welcoming of Mozilla's manifest as initial input - but the reality is that stuff is probably going to have to change in ways that may break compatibility with our format.

Question is, what's the best way to handle breaking changes?

[Matt Basta]

> Which solutions do you propose in order to make it evolves ?

I've already proposed (in bugs and on this mailing list) a means of specifying icons by platform and potentially density.

Assuming that the format that Mounir proposes were to become a reality, I'd prefer--rather than breaking backwards compatibility--that we create a new field ("graphics" or something along those lines) and deprecate "icons". Developers could support older devices indefinitely in that way without affecting forward compatibility.

----- Original Message -----
From: "Vivien" <vnic...@mozilla.com>
To: "Matt Basta" <mba...@mozilla.com>, "Mounir Lamouri" <mou...@lamouri.fr>
Cc: "Marcos Caceres" <mcac...@mozilla.com>, "Jonas Sicking" <jo...@sicking.cc>, "Tim Guan-tin Chien" <timd...@mozilla.com>, "dev-webapps" <dev-w...@lists.mozilla.org>
Sent: Monday, June 17, 2013 10:44:20 AM
Subject: Re: Icon sizes and display densities

[Mounir Lamouri]

On 17/06/13 18:43, Marcos Caceres wrote:
> On Monday, June 17, 2013 at 5:11 PM, Mounir Lamouri wrote:
>

>> Hi,
>>
>> I would like to resurrect this thread with the following proposal:
>> "icons" will contain an array of objects that will have one mandatory
>> property named 'href'.
>

> "Mandatory" here means that if href is missing or not a URL, then it is in error and the object is ignored (and a warning is reported in the error console).

Yes. Just ignore the entry if there is no 'href'.

> Also, maybe "src" might be a more appropriate name for the member as it matches img tag.

"src" might be better than "href" indeed. I honestly don't care.
Supporting both would also be fine for me.

>> There will be three optional properties: 'width', 'height' and
>> 'density'. 'width' and 'height' will be a number expressing the size of
>> the icon in pixels and 'density' will for the moment be something in the
>> following set { "1x", "1.5x", "2x", "3x" }.
>

> We probably don't need to declare "x", as it's redundant in that the member is "density". If we want to support other types of "density" in the future, we can qualify those. Right now, the semantics of density is "device pixel ratio".
>
> Also, my personal experience with "2x" and "3x" is that it's easy to get wrong, because people are very used to writing "x2" and "x3".

I do not have a strong opinion on that. I agree that 1x 2x 3x are
commonly used and it might be a bit bothering to risk mistakes by
requesting the x.
In the other hand, we have no idea what is going to be the next common
thing. Will developers soon use "XXXdpi", "YYYdpi", "ZZZdpi". In that
case not having to specify "dpi" would be great for them.

Basically, not having a default would prevent us from having the wrong
default later but I do not have a strong opinion on that matter and we
should definitely have this discussed with people who know more on that
topic.

>> When the entry is a vectorial based image, if it has no size
>> information, it will be used every time an image with a size not in the
>> array is requested.
>

> There is currently no information that allows one to determine the type of an image.
>
> Options:
> 1. type member (e.g., "type": "image/svg")
> 2. head request (expensive - and might not yield anything useful)
> 3. heuristics, like checking for a file extension (can be unreliable - doesn't help for dynamically generated content or content with no extension… could also download the first few bytes to check the magic number, but it's also expensive)

That's a good point. I think 1 isn't a good solution because it wouldn't
work if the content is dynamically generated. In other words, it might
quite the same as using extensions.

How reliable would the header be?

--
Mounir

[Mounir Lamouri]

Jonas and I have been talking about this a couple of times. This is
something that also applies to APIs. If we change an API to something
drastically different we might want to be able to do that without
breaking too many applications. A solution to do this would be to
introduce a property in the manifest file like "manifest_version" or
"api_version" or "platform_version" (whatever...).

The manifest parsing would depend on the version number and the
available APIs might too. Some manifest properties and APIs would only
be available to newer versions and we could deprecate older versions and
then even stop supporting them.

The problem of that solution is that it sounds pretty specific to
implementations trying to experiment things. We could definitively make
this Mozilla only with something like "platform_version": "tef",
"platform_version": "leo", ... Then, the W3C specification might or
might not specify a system where there is such property (which would
have different set of values).

How does that sound?

--
Mounir

[Travis Choma]

Mounir, this sounds reasonable to me. Google also had to version their manifest file to deal with changes they introduced in v2 but still wanted v1 manifests to work properly and retain their original syntax and semantics.

Cheers,
-Travis

----- Original Message -----
From: "Mounir Lamouri" <mou...@lamouri.fr>

[Marcos Caceres]

On Tuesday, 18 June 2013 at 13:35, Mounir Lamouri wrote:

> On 17/06/13 18:43, Marcos Caceres wrote:
> > On Monday, June 17, 2013 at 5:11 PM, Mounir Lamouri wrote:
>
> > Also, maybe "src" might be a more appropriate name for the member as it matches img tag.
>
>
> "src" might be better than "href" indeed. I honestly don't care.
> Supporting both would also be fine for me.

We should only support support one (IMO, "src") - otherwise, it will be confusing.

> > > There will be three optional properties: 'width', 'height' and
> > > 'density'. 'width' and 'height' will be a number expressing the size of
> > > the icon in pixels and 'density' will for the moment be something in the
> > > following set { "1x", "1.5x", "2x", "3x" }.
> >
> >
> > We probably don't need to declare "x", as it's redundant in that the member is "density". If we want to support other types of "density" in the future, we can qualify those. Right now, the semantics of density is "device pixel ratio".
> >
> > Also, my personal experience with "2x" and "3x" is that it's easy to get wrong, because people are very used to writing "x2" and "x3".
>
> I do not have a strong opinion on that. I agree that 1x 2x 3x are
> commonly used and it might be a bit bothering to risk mistakes by
> requesting the x.
> In the other hand, we have no idea what is going to be the next common
> thing. Will developers soon use "XXXdpi", "YYYdpi", "ZZZdpi". In that
> case not having to specify "dpi" would be great for them.

People seem familiar with dppx because of iOS safari's window.devicePixelRatio. However, it's not clear most people understand what dppx actually is or how it works, as it's hard to grasp because it's a relative unit to CSS pixels. Regardless, places where icons are displayed generally will run as if <meta viewport=devicewidth>, in which case dppx should be *roughly*:

1 = non-retina
2 = retina
3 = ultra high density. Starting so see some of these (see [1] for a list)
4 = 8k displays (~beyond 2016) 7680x4320 on 13" - can't predict the future, but it's a possibility that there may be devices packing this many pixels into a small display around 2020.

I think also dpi might become kinda meaningless when icons interact with virtual viewports based on CSS pixels - like if the OS was run on a device supporting 3dppx but virtualized to run as if it was 2dppx (kinda like what iOS does with legacy 1dppx iPhone apps running on the new iPad).

> Basically, not having a default would prevent us from having the wrong
> default later but I do not have a strong opinion on that matter and we
> should definitely have this discussed with people who know more on that
> topic.

Sure, we are not codifying this in stone right now. We are using it as the basis of a proposal to take back to the W3C. We should hit the CSS WG for guidance here (or CSS people at Moz, like Elika).

We can also reach out to the W3C's Responsive Images Community Group for discussion. There are a lot of excellent designers in that CG with experience working on these kinds of problems.

> > > When the entry is a vectorial based image, if it has no size
> > > information, it will be used every time an image with a size not in the
> > > array is requested.
> >
> >
> > There is currently no information that allows one to determine the type of an image.
> >
> > Options:
> > 1. type member (e.g., "type": "image/svg")
> > 2. head request (expensive - and might not yield anything useful)
> > 3. heuristics, like checking for a file extension (can be unreliable - doesn't help for dynamically generated content or content with no extension… could also download the first few bytes to check the magic number, but it's also expensive)
>
>
> That's a good point. I think 1 isn't a good solution because it wouldn't
> work if the content is dynamically generated.

I'm not sure I follow? If you have:

{src: "foo", width: "64", height: "64", type: "image/svg"}

The UA assumes that the generated content is going to be "image/svg"?… more below.

> In other words, it might
> quite the same as using extensions.
>
> How reliable would the header be?
>

Given the above:
1. User agent that doesn't support SVG can ignore this icon (based on type member).
2. User agent that support SVG can confidently download this icon for usage:
- if the author made a mistake and it's not SVG, then the Content-Type header is authoritative (e.g., image/png). If the Content-Type header is missing or in error - content type sniffing applies.


- if the content is unrecognised once downloaded - then it's just ignored.

What am I missing?

[1] https://github.com/ResponsiveImagesCG/picture-element/wiki/Display-technologies:-beyond-Retina

[Marcos Caceres]

On Tuesday, 18 June 2013 at 13:41, Mounir Lamouri wrote:

> On 17/06/13 19:49, Marcos Caceres wrote:
> >
> >
> >
> > On Monday, June 17, 2013 at 6:01 PM, Matt Basta wrote:
> >
> > > I don't think this is viable solution since it's not backwards compatible. Older devices won't be able to understand the manifest.
> >
> > So, we are probably going to keep hitting this problem going forward, as we are not standardizing just Mozilla's manifest format (we are trying to learn from all available formats to create a solution that is right for the Web). Other W3C members have their own requirements, etc. and they've been quite welcoming of Mozilla's manifest as initial input - but the reality is that stuff is probably going to have to change in ways that may break compatibility with our format.
> >
> > Question is, what's the best way to handle breaking changes?
>
> Jonas and I have been talking about this a couple of times. This is
> something that also applies to APIs. If we change an API to something
> drastically different we might want to be able to do that without
> breaking too many applications. A solution to do this would be to
> introduce a property in the manifest file like "manifest_version" or
> "api_version" or "platform_version" (whatever...).
>
> The manifest parsing would depend on the version number and the
> available APIs might too. Some manifest properties and APIs would only
> be available to newer versions and we could deprecate older versions and
> then even stop supporting them.
>
> The problem of that solution is that it sounds pretty specific to
> implementations trying to experiment things. We could definitively make
> this Mozilla only with something like "platform_version": "tef",
> "platform_version": "leo", ... Then, the W3C specification might or
> might not specify a system where there is such property (which would
> have different set of values).
>
> How does that sound?

I think it sounds ok for the Moz side (as we can control how long we support a format version for, etc.) - but adding a manifest versioning scheme for the Web platform (W3C-side) won't fly because it would be difficult to maintain across user agents.

Also, feeding a Mozilla manifest to a W3C conforming implementation will also result in no icons (unless we change the name of the property on the W3C side as Matt suggested, but I doubt people will support that to accommodate legacy content from a single store - 'icons' is just too perfect a name to be owned by Mozilla).

Another option to consider is the contract that is made between the app developer and the "navigator.mozApps.install" API. This API basically says "install a Mozilla-App" and not "install a W3C conforming app".

To cut a long story short: there is no way to install a Moz app on a W3C conforming runtime. The W3C hosted app does not currently use any kind of install API (unlike FxOS, it relies on the <link> element to advertise it's "install-ability"). In practice, this would mean developers would have to keep two versions of their manifests: one for FxOS and another for W3C compatible UAs. I think that is ok as a transitional strategy.

If the manifest is served using PHP, then it would basically just mean having some conditional code like:

//request URL for w3c manifest
example.com/manifest

//request URL for mozilla
example.com/manifest?type=mozilla


If type = mozilla, then the developer can just conditionally filter out the mozilla stuff. Or you just have two files.

For packaged apps, we can use a different file name on the W3C side to bypass this problem (config.json) or something.

[Marcos Caceres]

On Tuesday, 18 June 2013 at 16:33, Travis Choma wrote:

> Mounir, this sounds reasonable to me. Google also had to version their manifest file to deal with changes they introduced in v2 but still wanted v1 manifests to work properly and retain their original syntax and semantics.
>

This could solve problems going forward, but current generation of devices would still be affected as they would just ignore "manifest_version" (i.e., they remain version agnostic - hence icon remains a problem).

As I understand it "manifest_version" literally means "process this manifest with this particular code path". We have to be careful that this doesn't get crazy, because if we start changing stuff and we want to support legacy content, then we need to make sure everything for each manifest_version continues to work without regressions. It also ties the manifest to a versioning system, which means we would need rules about what constitutes a version change and what happens if version 3 or 4 stuff appears in the manifest marked as 2 (ignore it? use it?).

Google can get away with using this scheme because their apps can only be installed form their store (and not the open Web) - hence, they can remove apps with outdated manifests from their store when they feel like it. In our case, we have to be more mindful because users are not restricted from where they install hosted apps from (and we have no way of forcing developers to update outdated manifests on the open Web).

Just some thoughts…

--
Marcos Caceres

[Marcos Caceres]

On Monday, 24 June 2013 at 19:48, Jonas Sicking wrote:

>
> On Jun 18, 2013 5:51 PM, "Marcos Caceres" <mcac...@mozilla.com (mailto:mcac...@mozilla.com)> wrote:
> > I think it sounds ok for the Moz side (as we can control how long we support a format version for, etc.) - but adding a manifest versioning scheme for the Web platform (W3C-side) won't fly because it would be difficult to maintain across user agents.
>

> My thinking was to use some sort of versioned manifest for now, as long as we only use it in prefixed mozApps.install.
> Once we switch to an unprefixed function, we also need to use a standardized manifest and forever maintain compatibility with that manifest format.

Agree. But can we treat them as separate things till we actually decide to formally support the W3C format? That frees us to experiment, innovate, and make (hopefully few) mistakes that we can correct with versioning. It gives us a good way to feed back to the Web without using the Web as a place of experimentation while also enabling new features.

If we get agreement as a group on this, I think it would help a lot. It doesn't mean the two formats will necessarily deviate a lot - but conceptually, it does free us a little bit.

WDYT?

[Mounir Lamouri]

I am in favour of that.

-- Mounir

[Marcos Caceres]

On Monday, June 24, 2013 at 7:48 PM, Jonas Sicking wrote:

>
> My thinking was to use some sort of versioned manifest for now, as long as we only use it in prefixed mozApps.install.
>
>
> Once we switch to an unprefixed function, we also need to use a standardized manifest and forever maintain compatibility with that manifest format.

Ok, here is a shot at this to get the ball rolling… Below is a quick straw person Mounir and I put together over IRC.

In order to limit potential issues with breaking changes in the FxOS manifest going forward, as well as to provide us with a way to add new (non-backwards compatible) features through the FxOS manifest format, it was proposed that a versioning scheme be introduced. It is assumed that the user agent will continue to support legacy content indefinitely (that is, all V1 content going forward).

# The `manifest_version` member
The `manifest_version` member denotes the manifest version used by the application. It's type is expected to be a non-negative integer greater than 0.

Notes on the type: ECMAScript's ToNumber() algorithm is used to perform the conversion from JSON, hence the following are all valid and equivelent: "2", " 2 ", 2, [2].

## example of usage
{
...
"manifest_version": 2
...
}

##Authoring guidance and validation
Unless version specific members are included in the manifest, it is optional for a developer to include the `manifest_version` member. When the member is missing, the user agent assumes the value to be 1. However, if version specific members are included in the manifest, and the `manifest_version` is missing or in error, then members that rely on `manifest_version` to have some effect will be ignored by the user agent.

A manifest validator must validate that `manifest_version` contains a non-negative integer greater than 0.

Note: Future versions of FxOS may require the `manifest_version` member to be present in a manifest, and to be set to at least the number 2 (e.g., if some future member becomes required for security reasons). However, legacy content should continue to work and offending members may end up being ignored by the user agent.

## Steps to determine the version number
The following steps take a JSON-parsed manifest as an argument. The steps always return a non-negative integer greater than 0.

1. If the manifest does not have its own property "manifest_version", return 1 and terminate this algorithm.
2. Let potential-version be the result of running ECMASscript's ToNumber(manifest_version).
3. If potential-version is a NaN or a number less than 1, warn the developer that the version is invalid. Return 1 and terminate this algorithm.
4. Return potential-version.

## Outstanding issues
If version is greater than the highest version number supported by the user agent, should the user agent treat the manifest as the highest manifest version it supports? Or reject the manifest outright as invalid?

If a manifest version number is invalid (i.e., NaN, <= 0 ), is the manifest invalid?


--
Marcos Caceres

[Mounir Lamouri]

On 04/07/13 12:50, Marcos Caceres wrote:
> ## Outstanding issues
> If version is greater than the highest version number supported by the user agent, should the user agent treat the manifest as the highest manifest version it supports? Or reject the manifest outright as invalid?

I think the application should be marked as incompatible. Imagine I have
an old phone with a runtime that only understand manifest_version { 0,
1, 2 }. My phone doesn't supports newer versions but there are newer
versions out there like { 3, 4, 5 }. If an application is advertising
itself as manifest_version = 3, it is a hint that my phone will not be
able to run it. It *might* be able to run it but nothing is less sure.

> If a manifest version number is invalid (i.e., NaN, <= 0 ), is the manifest invalid?

I think we should use manifest_version = 0 as the current default
version. Hopefully no one will ever write manifest_version = 0 because
we would introduce that feature at the same time as we would introduce
manifest_version = 1.

Also, I would like to think about the path to standardisation. Google
Chrome Apps have the same concept (manifest_version) using numbers too.
Should we have a special token like "w3c" or "standard" that will be
required to use the standard manifest version? I think that would be
reasonable even though that means that if some applications were using
"w3c" as a value, it might break them :(

--
Mounir

[Marcos Caceres]

On Thursday, July 18, 2013 at 6:05 PM, Mounir Lamouri wrote:

> On 04/07/13 12:50, Marcos Caceres wrote:
> > ## Outstanding issues
> > If version is greater than the highest version number supported by the user agent, should the user agent treat the manifest as the highest manifest version it supports? Or reject the manifest outright as invalid?
>
>
>
> I think the application should be marked as incompatible. Imagine I have
> an old phone with a runtime that only understand manifest_version { 0,
> 1, 2 }. My phone doesn't supports newer versions but there are newer
> versions out there like { 3, 4, 5 }. If an application is advertising
> itself as manifest_version = 3, it is a hint that my phone will not be
> able to run it. It *might* be able to run it but nothing is less sure.

I'm really worried about this, as it's not very "webby": the manifest should hopefully not specify things that would cause the application itself to not be runnable (i.e., manifest stuff should just be harmless metadata with limited side effects … though CSP tightening already breaks this principle a bit). Having apps accessible through the Web browser, but then not installable because of a manifest version would be weird for hosted apps (which shouldn't need to be installed to be usable - as not all user agents may support installation - or users may want to "try before they buy/install").

It would also mean that certain devices would be tied to certain manifest versions (it's a nasty way to lock people out, without providing graceful degradation). This might lead to all sorts of version/device mappings, which would not be great IMO.

I think we should adopt a "do minimal harm" principle when adding new stuff to the manifest: meaning that stuff that is not understood is just ignored, ala HTML parsing style.

> > If a manifest version number is invalid (i.e., NaN, <= 0 ), is the manifest invalid?
>
>
> I think we should use manifest_version = 0 as the current default
> version. Hopefully no one will ever write manifest_version = 0 because
> we would introduce that feature at the same time as we would introduce
> manifest_version = 1.

I don't think the version number we start from actually matters from a technical standpoint. However, it might confuse people to see version 0 now and again. Version 1 is more "natural".

> Also, I would like to think about the path to standardisation. Google
> Chrome Apps have the same concept (manifest_version) using numbers too.

Yes. The proposal is more or less identical - though I don't know how they do their parsing.

> Should we have a special token like "w3c" or "standard" that will be
> required to use the standard manifest version? I think that would be
> reasonable even though that means that if some applications were using
> "w3c" as a value, it might break them :(
>

I would like to treat the formats as completely separate (we have different ways of installing these manifests as well as different MIME types, which serves as the differentiator). Any overlap between the two should be seen as coincidental - otherwise, things are going to get really messy.

[Mounir Lamouri]

On 18/07/13 18:44, Marcos Caceres wrote:
> On Thursday, July 18, 2013 at 6:05 PM, Mounir Lamouri wrote:
>
>> On 04/07/13 12:50, Marcos Caceres wrote:
>>> ## Outstanding issues
>>> If version is greater than the highest version number supported by the user agent, should the user agent treat the manifest as the highest manifest version it supports? Or reject the manifest outright as invalid?
>>
>>
>>
>> I think the application should be marked as incompatible. Imagine I have
>> an old phone with a runtime that only understand manifest_version { 0,
>> 1, 2 }. My phone doesn't supports newer versions but there are newer
>> versions out there like { 3, 4, 5 }. If an application is advertising
>> itself as manifest_version = 3, it is a hint that my phone will not be
>> able to run it. It *might* be able to run it but nothing is less sure.
>
> I'm really worried about this, as it's not very "webby": the manifest should hopefully not specify things that would cause the application itself to not be runnable (i.e., manifest stuff should just be harmless metadata with limited side effects … though CSP tightening already breaks this principle a bit). Having apps accessible through the Web browser, but then not installable because of a manifest version would be weird for hosted apps (which shouldn't need to be installed to be usable - as not all user agents may support installation - or users may want to "try before they buy/install").
>
> It would also mean that certain devices would be tied to certain manifest versions (it's a nasty way to lock people out, without providing graceful degradation). This might lead to all sorts of version/device mappings, which would not be great IMO.
>
> I think we should adopt a "do minimal harm" principle when adding new stuff to the manifest: meaning that stuff that is not understood is just ignored, ala HTML parsing style.

The idea of a manifest version isn't Web-y, indeed; we want to use that
so we can deprecate APIs, this is not at all something we do on the Web.

However, to take the example I pointed, if, as a developer, I say that
my application requires the version 3.0 and a user wants to install my
application but its device only knows the version 2.0 and earlier, what
should we do? We can't simply ignore the hint that the app might not
work. A solution could be to simply forbid installation but we can be
smarter about it and do like in AMO where the installation isn't allowed
unless the user check something that says "I want to try anyway".

This could indeed be used to evil goals but I am not sure what we can do
to prevent that. If we want to prevent any on purpose fragmentation
based on this feature, the only solution is to assume that all APIs will
stay for ever and the manifest_version property would not be needed.

Note that when I say that the manifest version is incompatible, I am
mostly worried about the usage of new features, not much about the
manifest format.

>> Should we have a special token like "w3c" or "standard" that will be
>> required to use the standard manifest version? I think that would be
>> reasonable even though that means that if some applications were using
>> "w3c" as a value, it might break them :(
>>
>
> I would like to treat the formats as completely separate (we have different ways of installing these manifests as well as different MIME types, which serves as the differentiator). Any overlap between the two should be seen as coincidental - otherwise, things are going to get really messy.

I am not a big fan of having a fuzzy plan. I think we should have
something more defined. What is the current MIME Type Chrome Apps and
Firefox OS apps require? What would be the W3C MIME Type? Can we really
assume that developers will simply expose their manifest using another
MIME Type?
Should we consider as a goal to get backward compatibility? I am afraid
that new comers will have to implement a mix of Mozilla's and Google's
proprietary formats. Also, what should we do if we don't expose a
manifest_version specific to the standard format and a new comer
implements the spec but the manifest is using manifest_version='x' which
would be ignored by the implementation but the manifest would be
half-working. A solution is indeed to change the MIME Type but then we
have another backward compatibility issue.

--
Mounir

[Vishwanathan Krishnamoorthy]

This may not be appropriate for the conversation here but manifest versions implies a way to version the runtime.
How would that work? based on the gecko version or a different scheme based on changes to Web APIs? (changes to existing or addition of new functionality)

regards
Vishy

----- Original Message -----
From: "Mounir Lamouri" <mou...@lamouri.fr>
To: "Marcos Caceres" <mcac...@mozilla.com>

[Matt Basta]

In a similar vein (and not to de-rail conversation), can we plan to add an API which exposes the platform's support for manifest versions?

navigator.apps.supportsManifestVersion('moz') // legacy manifest support
navigator.apps.supportsManifestVersion(2)
navigator.apps.supportsManifestVersion(3)
// ...

[Mounir Lamouri]

On 25/07/13 16:52, Vishwanathan Krishnamoorthy wrote:
>
> This may not be appropriate for the conversation here but manifest versions implies a way to version the runtime.
> How would that work? based on the gecko version or a different scheme based on changes to Web APIs? (changes to existing or addition of new functionality)

The idea would be that some APIs would be needed only if the developer
requests a version X. Version X will also deprecate some APIs. That will
allow us to slowly remove some APIs from the platform. This is roughly
the kind of systems most platforms have with SDK versions.

--
Mounir

[Mounir Lamouri]

On 25/07/13 19:55, Matt Basta wrote:
> In a similar vein (and not to de-rail conversation), can we plan to add an API which exposes the platform's support for manifest versions?
>
> navigator.apps.supportsManifestVersion('moz') // legacy manifest support
> navigator.apps.supportsManifestVersion(2)
> navigator.apps.supportsManifestVersion(3)
> // ...

What would be the use case for that?

-- Mounir

[Marcos Caceres]

On Thursday, July 25, 2013 at 3:00 PM, Mounir Lamouri wrote:

> On 18/07/13 18:44, Marcos Caceres wrote:
> > On Thursday, July 18, 2013 at 6:05 PM, Mounir Lamouri wrote:
>
> The idea of a manifest version isn't Web-y, indeed; we want to use that
> so we can deprecate APIs, this is not at all something we do on the Web.
>

I would strongly urge us to keep those two concerns separate - a manifest version should be to deprecate manifest things (e.g., if we move to support HD icons) - but should have no relationship to APIs. I.e., treat them as completely orthogonal.

In addition, we should only introduce manifest versioning when the time is right and when we have no other option.

I discuss API deprecation below. However, I see the Web not following a traditional software development model (i.e., it's versionless) as one of its core strengths as a platform - but that's my ideological position (did I spend too much time at the TAG?:)). I worry when I see us take Web technologies and start bolting on traditional software development paradigms onto them.

> However, to take the example I pointed, if, as a developer, I say that
> my application requires the version 3.0 and a user wants to install my
> application but its device only knows the version 2.0 and earlier, what
> should we do?
>

On the Web, it is assumed that developers would use graceful degradation techniques in such situations. I tend to trust developers want to do the right thing by their users - but I could be wrong. The data that I have on this is the use of modernizr using the WebDevData archive.

Running:
for b in */*.txt; do ( grep -lm 1 "modernizr" $b ); done | wc -l

Of 106,600 documents searched (representing the front page of a site), yields 2401 sites using modernizr: ~2.25%

That's at least indicative that quite a few developers care enough to include a library designed to deal with the above.

> We can't simply ignore the hint that the app might not
> work. A solution could be to simply forbid installation but we can be
> smarter about it and do like in AMO where the installation isn't allowed
> unless the user check something that says "I want to try anyway".
>

Sure. But like I said above, this is nothing new on the Web. We've being doing graceful degradation/progressive enhancements since at least 2003 [1]. Turned out IE stagnating the Web (and continuing to do so with IE7,8,9) taught developers a thing or two about this! :)

> This could indeed be used to evil goals but I am not sure what we can do
> to prevent that. If we want to prevent any on purpose fragmentation
> based on this feature, the only solution is to assume that all APIs will
> stay for ever and the manifest_version property would not be needed.
>

If we decouple the APIs and the Manifest, they become orthogonal - as I argued they should be.

> Note that when I say that the manifest version is incompatible, I am
> mostly worried about the usage of new features, not much about the
> manifest format.
>

Me too. But I'd like for us to deal with API deprecation in other ways - if it turns out that we need to deprecate APIs at all. I don't see us stopping support for all the currently prefixed ones in FxOS. It would be *nice* if we eventually enable the W3C ones that do the same thing, but that doesn't require versioning - that only requires simple JS feature detection: if("whatever" in window){ rockAndRoll();}.

> > > Should we have a special token like "w3c" or "standard" that will be
> > > required to use the standard manifest version? I think that would be
> > > reasonable even though that means that if some applications were using
> > > "w3c" as a value, it might break them :(
> > >
> >
> > I would like to treat the formats as completely separate (we have different ways of installing these manifests as well as different MIME types, which serves as the differentiator). Any overlap between the two should be seen as coincidental - otherwise, things are going to get really messy.
> >
>
>
> I am not a big fan of having a fuzzy plan.

Neither am I - this is no fuzzy plan - this is drawing a line in the sand here and we have the key bits in place already.

> I think we should have
> something more defined. What is the current MIME Type Chrome Apps and
> Firefox OS apps require?
>

FxOS doesn't require a mime type, last I checked (we only pay lip service to it).

FxOS is: application/x-web-app-manifest+json (not used)

Chrome doesn't seem to have one (at least, I could not find it), it's just JSON: thus, probably, application/json (and probably works with none).

> What would be the W3C MIME Type?
>

W3C is: webapp-manifest+json


See: http://manifest.sysapps.org/#media-type

However, it will also not require that document be served with a MIME type, as the presence of a MIME type cannot be relied on: too few developers have the ability to set such things on their servers so it's pointless to expect it (though we will still recommend it, as they can be somewhat useful in certain situations… maybe, sometimes).

> Can we really
> assume that developers will simply expose their manifest using another
> MIME Type?
>

That's not necessary. We have two completely distinct ways of handling installation of applications.

FirefoxOS uses `navigator.mozApps.install()`

The W3C spec uses:
<link rel="manifest" href="awesome.webapp">


See: http://manifest.sysapps.org/#linking

Even if we had an install API for W3C, it would not hang of "moz", obviously, so there is no clash.

> Should we consider as a goal to get backward compatibility?
>

IMO, no. This is too restrictive for FirefoxOS right now.

> I am afraid
> that new comers will have to implement a mix of Mozilla's and Google's
> proprietary formats.
>

Not if there is a W3C spec that's of quality and has actual implementers behind it.

> Also, what should we do if we don't expose a
> manifest_version specific to the standard format and a new comer
> implements the spec but the manifest is using manifest_version='x' which
> would be ignored by the implementation but the manifest would be
> half-working.
>

I must be missing something, but the only way that could happen is if someone tries to pass off a Mozilla or Chrome or even a Commons.js manifest as a W3C one. As silly as that is, the fact that it would "half work" would actually be a feature of the robustness of the W3C manifest parser - but it's only coincidental that they share properties (and that they are JSON).

Think of this as being akin the the HTML5 parser - you can throw any garbage at it and it will still give you a DOM.

> A solution is indeed to change the MIME Type but then we
> have another backward compatibility issue.
>

MIME types are not useful in practice, so it's best to not even consider them as a solution in our discussions.

[1] http://en.wikipedia.org/wiki/Progressive_enhancement

[Matt Basta]

The use case for a "supportsManifestVersion" API would be to allow marketplaces to determine whether they should show an app to a particular device. Imagine this scenario:

Acme App is for sale and uses manifest version X
User's device implements up to manifest version X - 1

If a marketplace doesn't know and can't detect that the user can't physically install the app (because their platform is too old or too new), then the user could be sent through a payment flow (navigator.pay), purchase the app, and then find out later that the app isn't able to be installed on their device. Having an API would allow the Marketplace to hide or blocks installs for the app. Similar APIs exist for the <video> and <audio> elements to detect codec support.

Having such an API would be critical for forwards and backwards compatibility.

----- Original Message -----
From: "Mounir Lamouri" <mou...@lamouri.fr>
To: "Matt Basta" <mba...@mozilla.com>
Cc: "Vishwanathan Krishnamoorthy" <vkrishn...@mozilla.com>, "Marcos Caceres" <mcac...@mozilla.com>, "dev-webapps" <dev-w...@lists.mozilla.org>, "Vivien Nicolas" <vnic...@mozilla.com>, "Tim Guan-tin Chien" <timd...@mozilla.com>, "Jonas Sicking" <jo...@sicking.cc>
Sent: Friday, July 26, 2013 9:46:34 AM
Subject: Re: Versioning system for manifest, Re: Migrating to W3C format, was Re: Icon sizes and display densities

[Marcos Caceres]

On Friday, 26 July 2013 at 22:37, Vishwanathan Krishnamoorthy wrote:

>
> ok thanks for the clarification, so manifest_version is specifically for the properties in the manifest and not the capabilities of the runtime.
>
> What triggers a version change? I can think of
> 1) modification to an existing property
> 2) Adding new properties
>
> 2 is fine but 1) IMO would break backward compatibility and would require app developers to maintain multiple versions of the app
>

Yeah, we shouldn't need to do 1), hopefully (fingers crossed, knock on wood!). But the option is always there if we _really_ need to. Even in case 2, we would only need a version change if the new property actually affected the runtime: consider, I don't think "description" is used by Gaia, is it? So stuff that we add just to support the store can be safely added to any version and is simply ignored by the runtime without affecting users.

[Marcos Caceres]

On Friday, July 26, 2013 at 6:36 PM, Matt Basta wrote:

> The use case for a "supportsManifestVersion" API would be to allow marketplaces to determine whether they should show an app to a particular device. Imagine this scenario:
>
> Acme App is for sale and uses manifest version X
> User's device implements up to manifest version X - 1
>
> If a marketplace doesn't know and can't detect that the user can't physically install the app (because their platform is too old or too new), then the user could be sent through a payment flow (navigator.pay), purchase the app, and then find out later that the app isn't able to be installed on their device.

We would only really need this if we add things to the manifest that break backwards compatibility in an unrecoverable way (I don't think we have done this yet?). The consequence is that users might be unnecessarily locked out of content. For example, if a developer copy/pastes someone else's manifest and doesn't actually understand the implications of using manifest_version="2". Or, the developer decides to use some feature Z, but also makes the content available through graceful degradation (this makes using graceful degradation pointless - as by opting into version N you automatically shut-out - or at least annoy with a prompt - users).

As the user's runtime can't predict the future (if it can support version x or not), it can unwittingly lock the user out of content - in a particularly discriminatory way. The fundamental flaw here is really with the business model that is guiding technical decisions (purchasing a unit - rather than paying to access a service). On the Web, there is no reason to not allow "try before you buy" to overcome the "but will it work?" problem.

One way around this would be to have the freedom to keep adding members to version 1 of the manifest format (if those properties don't affect compatibility), but then have a "restricted" version. I'm again not in favor of this, as it's user hostile and doesn't scale well (e.g., as a user, I own multiple devices, each supporting different device capabilities, browsers, etc.). Also, as I have mentioned elsewhere, manifest metadata should remain orthogonal to device capabilities.

> Having an API would allow the Marketplace to hide or blocks installs for the app. Similar APIs exist for the <video> and <audio> elements to detect codec support.

The above API is an unfortunate byproduct of the Codec Wars™ - certainly not something to be emulated or that can be compared to, IMO.

> Having such an API would be critical for forwards and backwards compatibility.
>

I think you might be correct but only for packaged apps - which sadly follow a traditional software development model (no "try-before-you-buy" support). However, a fundamental shift in thinking about what differentiates hosted apps from traditional [packaged] apps is needed here (i.e., Google's Play and Apple's iOS business models are incompatible with the decentralized/un-versioned nature of the Web).

Thus, the proposed API should never be needed for hosted apps because it would be inexcusable to get into the "but will it work on my device?" situation. The role of the payment API in this context is to enable access to functionality/service/products (some examples are purchasing private repo access on GitHub, buying games on Steam, purchasing a physical good on Etsy, and so on).

--
Marcos Caceres

[Matt Basta]

> We would only really need this if we add things to the manifest that break backwards compatibility in an unrecoverable way

Not the case. This feature is needed in order to prevent older devices from accessing content that they can't run. The app ecosystem can't rely on developers being good samaritans and always providing backward compatibility for every feature forever.

> (I don't think we have done this yet?).

We're presently dealing with the fallout from the addition of the `origin` field (albeit a packaged app-only field). It's not inconceivable that this will happen again.

> As the user's runtime can't predict the future (if it can support version x or not), it can unwittingly lock the user out of content - in a particularly discriminatory way.

Yes, but we live in a world with payments and apps that cost money. If a user pays for an app that requires a specific feature that's not supported on older platforms, the user is going to be really upset that they spent good money on an app that won't run. It should be preferred that users can't install an app spuriously rather than being able to pay money for it and then being unable to use it.

The implementation that the Firefox Marketplace uses doesn't disallow the install, we simply warn the user up and down that the app probably won't work if we think that it's incompatible with their device, and we also don't list it in search results with the default settings.

Imagine if you bought a car, but only after you'd signed the loan contracts you found out that it had the steering wheel on the opposite side that you're used to. The car doesn't function the way you'd like it to, and now you're stuck with it. That's a really crappy experience, and I'd rather have a nag screen than users clamoring for refunds or sending chargebacks.

> manifest metadata should remain orthogonal to device capabilities.

It's presently the case, and it seems (based on the drafts of the manifest spec) that the manifest contains fields that affect the functionality and behavior of the app. In fact, most of the fields in the Mozilla manifest docs affect the behavior of the app and aren't "metadata" at all.

> Thus, the proposed API should never be needed for hosted apps because it would be inexcusable to get into the "but will it work on my device?" situation.

Even now, this is false. Hosted apps can still require payment, and any hosted app can check that a proper receipt exists. There is nothing that requires a hosted app to support a "try-before-you-buy" or "freemium" model and it's unlikely that this will ever change, at least for the Firefox Marketplace.

----- Original Message -----
From: "Marcos Caceres" <mcac...@mozilla.com>
To: "Matt Basta" <mba...@mozilla.com>
Cc: "Mounir Lamouri" <mou...@lamouri.fr>, "Vishwanathan Krishnamoorthy" <vkrishn...@mozilla.com>, "dev-webapps" <dev-w...@lists.mozilla.org>, "Vivien Nicolas" <vnic...@mozilla.com>, "Tim Guan-tin Chien" <timd...@mozilla.com>, "Jonas Sicking" <jo...@sicking.cc>
Sent: Monday, July 29, 2013 10:43:38 AM
Subject: Re: Versioning system for manifest, Re: Migrating to W3C format, was Re: Icon sizes and display densities

[Marcos Caceres]

On Monday, July 29, 2013 at 7:13 PM, Matt Basta wrote:

> > We would only really need this if we add things to the manifest that break backwards compatibility in an unrecoverable way
>
>
> Not the case. This feature is needed in order to prevent older devices from accessing content that they can't run.

An API is not in the position to make this determination. It's just a way to side step a halting problem with unintended side-effects: you can't know if you can run the code until you try to run it.

> The app ecosystem can't rely on developers being good samaritans and always providing backward compatibility for every feature forever.

I think this is where we fundamentally disagree - this is a core tenant of the Web and Web applications. I put this burden on browsers in that I believe that browsers have an obligation to continue to support legacy content so long as a % of that content is on the Web. Developers should be expected to have their applications degrade gracefully - HTML is designed around this principle and these sort of APIs threaten to break this core principle of the Web.

> > (I don't think we have done this yet?).
>
>
> We're presently dealing with the fallout from the addition of the `origin` field (albeit a packaged app-only field). It's not inconceivable that this will happen again.

Adding origin is not a breaking change, AFAIK? It just means an app gains a stable human readable origin rather than a UUID.

> > As the user's runtime can't predict the future (if it can support version x or not), it can unwittingly lock the user out of content - in a particularly discriminatory way.
>
>
> Yes, but we live in a world with payments and apps that cost money. If a user pays for an app that requires a specific feature that's not supported on older platforms, the user is going to be really upset that they spent good money on an app that won't run.

But they are still going to be pissed off if they purchase something on device A, but it doesn't get installed on device B - specially when they got sold on something being a Website that should work on both devices by its very nature.

> It should be preferred that users can't install an app spuriously rather than being able to pay money for it and then being unable to use it.

Feature detection is only the tip of the iceberg of things that could prevent a user being able to use an application (e.g., an app expects a real keyboard or touch screen to be present, there is no network connection, some service the app depends on goes down, a regression in the OS slips through and causes the app to stop working, not enough memory on the device, etc.). The fundamental problem is still that they are getting potentially blocked from doing something in the first place with a technology that was architectured to not get into this situation (i.e., that degrades gracefully).

> The implementation that the Firefox Marketplace uses doesn't disallow the install, we simply warn the user up and down that the app probably won't work if we think that it's incompatible with their device, and we also don't list it in search results with the default settings.

Sure, but this is a problem because it gives developers an escape hatch to not degrade their apps gracefully.

> Imagine if you bought a car, but only after you'd signed the loan contracts you found out that it had the steering wheel on the opposite side that you're used to.

This is a bad example, because cars are the quintessential "try before you buy" - I don't know anyone who has bought a car without test driving it first. That aside…

> The car doesn't function the way you'd like it to, and now you're stuck with it. That's a really crappy experience, and I'd rather have a nag screen than users clamoring for refunds or sending chargebacks.

Now imagine, you buy the car, but it's able to adapt to its environment: you are out on the road, and the road suddenly turns to sand - the car automatically turns into a 4x4… you drive into water, it suddenly turns itself into a boat. You try to drive it through a wall, but it doesn't - so you tell the manufacturer you want to be able to drive it through a wall and a few minutes later, the manufacturer adds support for that. It's 15 years later, and you can still jump into it and it behaves the same way it always did. Sure, everyone around you is now driving flying cars that are able to go into space - but you don't care because your car still works as well as it did after it got its last service.

That's the beautiful thing about Web Apps - they are built to be adaptive - and that's the beautiful thing about Web browsers - they don't lock people out of their computers/phones/cars every 2 years like iOS, Android, and other proprietary platforms do. Websites I made when I was a kid still work exactly the same today as they did back then. Look - a page made in 1993 (and it works!): http://info.cern.ch/hypertext/WWW/TheProject.html

> > manifest metadata should remain orthogonal to device capabilities.
>
> It's presently the case, and it seems (based on the drafts of the manifest spec) that the manifest contains fields that affect the functionality and behavior of the app. In fact, most of the fields in the Mozilla manifest docs affect the behavior of the app and aren't "metadata" at all.

Sure. By device capabilities I mean enabling things like APIs (e.g., the need to declare geolocation in the manifest - which is redundant given that geolocation already prompts on use, and that location services could be controlled per application).

> > Thus, the proposed API should never be needed for hosted apps because it would be inexcusable to get into the "but will it work on my device?" situation.
> Even now, this is false. Hosted apps can still require payment, and any hosted app can check that a proper receipt exists.

Sure. But do any? Does anyone buy these things. I don't think we sell any apps at all ATM, do we?

> There is nothing that requires a hosted app to support a "try-before-you-buy" or "freemium" model and it's unlikely that this will ever change, at least for the Firefox Marketplace.
>

Take a look at the apps in the marketplace - the only category that resembles is games. The others all seem to follow the freemium model.

[Mounir Lamouri]

Hi,

I am forking this thread to something else because it seems that we have
a fundamental disagreement regarding the ability to deprecate some
Firefox OS APIs.

We added a lot of APIs that we would like to modify or remove recently
because of the Firefox OS effort - some/many of them being immature. The
natural way of doing things in the Web would be to simply wait until,
maybe, some day, those APIs would have a marketshare so low that it
would not disrupt to simply remove them.

However, most of those APIs were not added to the Web but to some
extension of it living in packaged/privileged applications. Those
applications have their content inside a zip file, have a manifest and
will be only installable via the Firefox Marketplace. This is a very
different setup than the Web, this is more a technology based on the Web
Platform than really the Web given that some key features like a
decentralised system do not exist.

In a centralised system, it is way simpler to deprecate things and I
think we should take this opportunity. Not because we want to violate
the basic rules of the Web but because we should use that situation to
make packaged applications a playground where we can try APIs without
being forced to support them forever.

There are not that many APIs created specifically for Firefox OS that
end up in hosted web applications (on top of my head, I see Screen
Orientation, mozApp and Alarm API). For those, we should have a
case-by-case decision regarding their future but I guess the usual Web
way of doing things should work.

I understand that using manifest_version for this would not be the best
property name. Maybe we should use 'runtime_version'. Though, I now
wonder if we would need a 'manifest_version' ;)

I would be interested to hear feedback regarding this, especially from
Marcos who did not look very happy with the idea of having a deprecation
system.

Cheers,
--
Mounir

[jsmith....@gmail.com]

Can I make a suggestion that we just start a new thread for the item you've brought up in this topic? This thread appears to be never ending at this point going in multiple directions, which makes it a bit hard to follow.

[Travis Choma]

Comments below:

I think this is the crux of it, and I agree that we have an opportunity to introduce a mechanism to promote iteration, experimentation and improvement of early apis.

What is more controversial is how to achieve this. I think versioning of the runtime is well worth thinking through. Perhaps we need additional mechanisms as well to better communicate the maturity of a given api to app developers. I know we've prefixed new/unstable apis in the past but another possibility in very early stage apis would be to have something like Chrome Apps have, where there is an explicit 'experimental' permission that the app has to list in it's permissions field in the manifest in order to access any experimental apis (with or without the need to also toggle a flag in the browser/runtime), further emphasizing the maturity of a given api to the app developer.

-Travis

[Marcos Caceres]

On Tuesday, July 30, 2013 at 2:07 PM, Mounir Lamouri wrote:

> Hi,
>
> I am forking this thread to something else because it seems that we have
> a fundamental disagreement regarding the ability to deprecate some
> Firefox OS APIs.
>
> We added a lot of APIs that we would like to modify or remove recently
> because of the Firefox OS effort - some/many of them being immature. The
> natural way of doing things in the Web would be to simply wait until,
> maybe, some day, those APIs would have a marketshare so low that it
> would not disrupt to simply remove them.
>
> However, most of those APIs were not added to the Web but to some
> extension of it living in packaged/privileged applications. Those
> applications have their content inside a zip file, have a manifest and
> will be only installable via the Firefox Marketplace. This is a very
> different setup than the Web, this is more a technology based on the Web
> Platform than really the Web given that some key features like a
> decentralised system do not exist.

Agreed.

> In a centralised system, it is way simpler to deprecate things and I
> think we should take this opportunity. Not because we want to violate
> the basic rules of the Web but because we should use that situation to
> make packaged applications a playground where we can try APIs without
> being forced to support them forever.

I think that is fine, so long as it does not adversely affect users - i.e., if we are going to remove/change APIs, we need a nice transitional path for developers (including actively helping them migrate to the new APIs) and we need to continue to support the old APIs for a while (till the content relying on the deprecated stuff is insignificant - channelling a bit of Matt Basta here: if people paid for a packaged app, that app should hopefully work for the life of their device).

The question is, what APIs do we want to deprecate? and what would we replace them with (the W3C ones or new FxOS-based ones)?

> There are not that many APIs created specifically for Firefox OS that
> end up in hosted web applications (on top of my head, I see Screen
> Orientation, mozApp and Alarm API). For those, we should have a
> case-by-case decision regarding their future but I guess the usual Web
> way of doing things should work.

Agreed. BTW, I'm supportive that FxOS gives us a way to iterate ideas that we can then attempt to standardize.

> I understand that using manifest_version for this would not be the best
> property name. Maybe we should use 'runtime_version'. Though, I now
> wonder if we would need a 'manifest_version' ;)
>
> I would be interested to hear feedback regarding this, especially from
> Marcos who did not look very happy with the idea of having a deprecation
> system.
>

I think we need to consider API transitions on a case by case basis (and then look at them as a group). If there is a backwards compatible "quick win" way to extend/deprecate functionality in APIs without needing a versioning scheme, we should use that (see David Bruant's proposal about DOMRequest extending Promises)… otherwise, we could group a large change-set and call it version.next.

Sorry about the rushed email and not having any real solutions here - but I'm about to vanish on vacation so trying to finish off a million things today:( Happy to help with this when I'm back!

[Travis Choma]

Marcos,

All good points, and definitely things we need to consider.

I agree that versioning the manifest comes with a responsibility to manage that process and make sure new versions are being released thoughtfully and on reasonably long cycles, but I think it's a good tool to have to allow us to surmount issues relating to existing fields that we didn't consider at the time (I'd be interested in hearing other suggestions beyond versioning that addresses this without having to rename fields all the time). And I agree, given that the current manifest isn't versioned makes things tricky.

If we are using versioning, and the manifest is marked v2 but has v3 properties in it, I would assume that it would be parsed as a v2 manifest and those v3/v4 fields would be ignored. The developer would need to correct his or her mistake in this case.

And in Google's case the phase out of v1 support is happening over the course of 6 months, first blocking submission and then eventual delisting apps. We'd have to figure out something similar to reduce the maintenance burden. Having multiple marketplaces is certainly a wrinkle. But as the platform/apis change we'll have to have some way of communicating to marketplaces that certain things/versions become deprecated over time.

Best,
-Travis

[Marcos Caceres]

On Tuesday, 18 June 2013 at 17:37, Travis Choma wrote:

> Marcos,
>
> All good points, and definitely things we need to consider.
>
> I agree that versioning the manifest comes with a responsibility to manage that process and make sure new versions are being released thoughtfully and on reasonably long cycles,

I would consider the long cycle thing a problem (for the same reason we've moved browsers to be evergreen).

> but I think it's a good tool to have to allow us to surmount issues relating to existing fields that we didn't consider at the time (I'd be interested in hearing other suggestions beyond versioning that addresses this without having to rename fields all the time). And I agree, given that the current manifest isn't versioned makes things tricky.

If we assume that the W3C and the Mozilla manifest are the same thing: the only thing I can think of is that new proprietary members should be prefixed (as the API was) going forward. Of course, this opens up the vendor prefixing hodge-podge - so I would not be in favour of this personally.

If we assume that the W3C and the Mozilla format are totally different manifests formats (they just kinda look the same accidentally), then we can easily come up with some clever strategies to continue to evolve our format without caring about the W3C format (our format serves to inform the W3C one, as does the Google format - but that's all). This is ok - but we need to draw a line in the sand, IHMO. Given my current thinking, I would be in favour of this as it gives us more freedom to move.

> If we are using versioning, and the manifest is marked v2 but has v3 properties in it, I would assume that it would be parsed as a v2 manifest and those v3/v4 fields would be ignored. The developer would need to correct his or her mistake in this case.

Right. I guess the same applies with v1 members in a v2 manifest. Note that if we don't end up making any breaking changes to our format, we can continue on happily with what we currently have.

> And in Google's case the phase out of v1 support is happening over the course of 6 months, first blocking submission and then eventual delisting apps. We'd have to figure out something similar to reduce the maintenance burden.

Right. I guess we would have to enforce this at the UA level also.

> Having multiple marketplaces is certainly a wrinkle. But as the platform/apis change we'll have to have some way of communicating to marketplaces that certain things/versions become deprecated over time.
>

Yes, for FxOS specific market places that would be the case.

[Mounir Lamouri]

On 18/06/13 17:40, Marcos Caceres wrote:
> I'm not sure I follow? If you have:
>
> {src: "foo", width: "64", height: "64", type: "image/svg"}
>
> The UA assumes that the generated content is going to be "image/svg"?… more below.

Yes. But what if the icon might be a bitmap format or a vectorial format
depending on some parameters?

>> In other words, it might
>> quite the same as using extensions.
>>
>> How reliable would the header be?
>>
>
> Given the above:
> 1. User agent that doesn't support SVG can ignore this icon (based on type member).
> 2. User agent that support SVG can confidently download this icon for usage:
> - if the author made a mistake and it's not SVG, then the Content-Type header is authoritative (e.g., image/png). If the Content-Type header is missing or in error - content type sniffing applies.
>
>
> - if the content is unrecognised once downloaded - then it's just ignored.
>
> What am I missing?

Maybe the case above?

--
Mounir

[Marcos Caceres]

On Wednesday, 19 June 2013 at 10:58, Mounir Lamouri wrote:

> On 18/06/13 17:40, Marcos Caceres wrote:
> > I'm not sure I follow? If you have:
> >
> > {src: "foo", width: "64", height: "64", type: "image/svg"}
> >
> > The UA assumes that the generated content is going to be "image/svg"?… more below.
>
> Yes. But what if the icon might be a bitmap format or a vectorial format
> depending on some parameters?

If the parameters are expressed explicit through the URL, then one declares two or more icons:

{src: "foo?format=svg", width: "64", height: "64", type: "image/svg"}
{src: "foo?format=jpeg", width: "64", height: "64", type: "image/jpeg"}

{src: "foo?format=webp", width: "64", height: "64", type: "image/webp"}


In the case where the type is server determined (e.g., content negotiation or UA string), the developer is basically agreeing to deal with it, So the following is still ok:

{src: "foo?format=random", width: "64", height: "64"}

The content negotiation case can be problematic (for devs) as UAs basically say "I'll accept anything you got!" (image/* and */*) in the Accept header for image requests. See:

https://developer.mozilla.org/en-US/docs/HTTP/Content_negotiation#Values_for_an_image

[Matt Basta]

Why not just have {"src": "...", "scalable": true} and let the UA figure it out. If it's a bitmap, try and scale it anyway (it'll be blurry, but that's the dev's fault). If the UA doesn't get scalable for any of the icons, it shouldn't scale them (unless none of them are the size it needs, in which case it should pick the closest size up and scale down or the nearest size down and scale up).

----- Original Message -----
From: "Marcos Caceres" <mcac...@mozilla.com>

[Marcos Caceres]

Hi Matt,

On Wednesday, June 19, 2013 at 4:04 PM, Matt Basta wrote:

> Why not just have {"src": "...", "scalable": true} and let the UA figure it out.

Is this in conjunction to having a width and height?

> If it's a bitmap, try and scale it anyway (it'll be blurry, but that's the dev's fault). If the UA doesn't get scalable for any of the icons, it shouldn't scale them (unless none of them are the size it needs, in which case it should pick the closest size up and scale down or the nearest size down and scale up).

Please read over the previous research and links I posted from icon creators about scaling issues. Generally, you only want to scale down, only scale up if you have no other option.

--
Marcos Caceres

[Matt Basta]

> Is this in conjunction to having a width and height?

It could be. The Marketplace enforces icons being square (and the MDN spec states "Icons must be square and are intended to visually represent the app."), so width and height don't matter a whole lot for vector graphics. If you don't specify a width and height and you do specify a scalable graphic, it should be assumed that the image is scalable to any size.

If you do provide a width and height, the UA could choose the scalable icon with the closest proportions to what's needed (allowing the developer to provide more appropriate icons at different sizes).

> Generally, you only want to scale down, only scale up if you have no other option.

Yes, that's what I meant. If the UA is looking for a 64x64 icon and there's no scalable graphics and the largest icon provided is 32x32, the UA would be forced to scale up.

----- Original Message -----
From: "Marcos Caceres" <mcac...@mozilla.com>
To: "Matt Basta" <mba...@mozilla.com>
Cc: "dev-webapps" <dev-w...@lists.mozilla.org>, "Vivien Nicolas" <vnic...@mozilla.com>, "Jonas Sicking" <jo...@sicking.cc>, "Tim Guan-tin Chien" <timd...@mozilla.com>, "Mounir Lamouri" <mou...@lamouri.fr>
Sent: Wednesday, June 19, 2013 8:26:45 AM
Subject: Re: Icon sizes and display densities

[Jonas Sicking]

On Jun 18, 2013 5:51 PM, "Marcos Caceres" <mcac...@mozilla.com> wrote:
>
>
>
> On Tuesday, 18 June 2013 at 13:41, Mounir Lamouri wrote:
>
> > On 17/06/13 19:49, Marcos Caceres wrote:
> > >
> > >
> > >
> > > On Monday, June 17, 2013 at 6:01 PM, Matt Basta wrote:
> > >
> > > > I don't think this is viable solution since it's not backwards
compatible. Older devices won't be able to understand the manifest.
> > >
> > > So, we are probably going to keep hitting this problem going forward,
as we are not standardizing just Mozilla's manifest format (we are trying
to learn from all available formats to create a solution that is right for
the Web). Other W3C members have their own requirements, etc. and they've
been quite welcoming of Mozilla's manifest as initial input - but the
reality is that stuff is probably going to have to change in ways that may
break compatibility with our format.
> > >
> > > Question is, what's the best way to handle breaking changes?
> >
> > Jonas and I have been talking about this a couple of times. This is
> > something that also applies to APIs. If we change an API to something
> > drastically different we might want to be able to do that without
> > breaking too many applications. A solution to do this would be to
> > introduce a property in the manifest file like "manifest_version" or
> > "api_version" or "platform_version" (whatever...).
> >
> > The manifest parsing would depend on the version number and the
> > available APIs might too. Some manifest properties and APIs would only
> > be available to newer versions and we could deprecate older versions and
> > then even stop supporting them.
> >
> > The problem of that solution is that it sounds pretty specific to
> > implementations trying to experiment things. We could definitively make
> > this Mozilla only with something like "platform_version": "tef",
> > "platform_version": "leo", ... Then, the W3C specification might or
> > might not specify a system where there is such property (which would
> > have different set of values).
> >
> > How does that sound?
> I think it sounds ok for the Moz side (as we can control how long we
support a format version for, etc.) - but adding a manifest versioning
scheme for the Web platform (W3C-side) won't fly because it would be
difficult to maintain across user agents.

My thinking was to use some sort of versioned manifest for now, as long as
we only use it in prefixed mozApps.install.

Once we switch to an unprefixed function, we also need to use a
standardized manifest and forever maintain compatibility with that manifest
format.

/ Jonas