Re: Unzipping content into current directory widely considered poor practice

On Fri, Nov 20, 2009 at 8:48 AM, Dan Brickley <danbri@danbri.org> wrote:
> Hello,
>
> I understand from http://www.w3.org/TR/2009/WD-widgets-20091029/ that
> this is the place to direct my feedback on the widget packaging spec,
> and that I have missed the Last Call deadline by one day. I hope you
> will consider my plea anyway, since it is based on evaluation of an
> implementation I only discovered last night. See below for an issue I
> tried to raise with the implementor.
>
> It seems W3C Widget zip packages unload a mess of several files in the
> current working directory when unzipped.
>
> This is unfortunate and I urge you to consider a design that allows
> things to be kept in a single subdirectory.
>
> 1. the dominant convention in modern software development is that you
> can safely unwrap a .zip or .tar.gz in the current working directory,
> in the expectation that you'll find only a sensibly named
> subdirectory. Those who violate this expectation are often seen as
> making a basic beginners mistake. Encoding such a 'mistake' in a W3C
> REC both looks bad, and encourages bad practice.
>
> 2. by risking a mixup between pre-existing files and those from the
> archive file, we introduce the risk of confusion and inclarity, making
> widgets ever slightly harder to learn from. And or those who do try to
> learn from others works, we reward them by making a mess of their
> filetree. Assuming 1000 new developers decide each day to explore W3C
> Widget technology and learn by example, I expect 900+ of them will
> come with the reasonable assumption that a zip file can be safely
> unpacked in a directory that has already got other stuff in it
> (including possibly files with common names like index.html). Mixing
> up files will be annoying; accidentally overwriting files will be
> infuriating....
>
> 3. Are we confident that all unzip tools will ask nicely before
> overwriting existing files? A quick test on my machine at least gave
> me a warning.
>
> eg.
> TellyClub:~ danbri$ mkdir w3ctest
> TellyClub:~ danbri$ cd w3ctest/
> TellyClub:w3ctest danbri$ echo '<html6>my original valuable html
> document</>' > index.html
> TellyClub:w3ctest danbri$ curl -Os http://berjon.com/tmp/a-widget.wgt
> TellyClub:w3ctest danbri$ unzip a-widget.wgt
> Archive:  a-widget.wgt
>  inflating: config.xml
>  inflating: icon.svg
>   creating: img/
>  inflating: img/me.jpg
> replace index.html? [y]es, [n]o, [A]ll, [N]one, [r]ename:
>
>
> Thanks for considering my request.
>

I spoke to Dan about the above offline, we feel that adding the
following non-normative authoring guideline into the specification
would be sufficient to address Dan's concerns:

Under section "Reserved File and Folder Names"

"Authoring Guideline: Authors are strongly encourage to package all
files, except the reserved files and the  container for localized
content, within a single subdirectory named, for instance, after the
widget. This is to avoid unzipping several files into the end-user's
current working directory. Future versions of this specification may
include rules for locating index.html and config.xml within such
directories.

For example, best practice for packaging a widget would look something
like this:

config.xml
index.svg
index.html
clock/
            images/
            screens/
locales/
           jp/
               clock/
                           images/
                           assets/
           fr/
               clock/
                           images/
                           assets/
"

As these comments came in after the deadline, I have not included the
text in the current spec. If the WG agrees, I will add them to
whatever the next publication will be (fingers crossed, it will be
PR).

Kind regards,
Marcos

-- 
Marcos Caceres
http://datadriven.com.au

Received on Friday, 20 November 2009 16:06:49 UTC