gnome-vfs API freeze items

[Maciej Stachowiak <mjs noisehavoc org>]

Below please find the list of potentially API-changing bugs for
gnome-vfs. This is definitely too long a list for 2.0, so the next
step is to prune the list. I have already punted the metadata items
and anything depending on them since Seth agreed to let me roll back
the metadata changes for now and do the work on a branch or in his
working directory until the code is ready.


Here is the bugzilla query to get uncategorized gnome-vfs API issues
(currently 40):

http://bugzilla.eazel.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=gnome-vfs&short_desc=%5E%5C%5BAPI%5C%5D&short_desc_type=regexp

Here is the bugzilla query to get gnome-vfs API issues definitively
planned for the 2.0 API freeze (currently 0):

http://bugzilla.eazel.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=gnome-vfs&short_desc=%5E%5C%5B2.0%5C%5D%5C%5BAPI%5C%5D&short_desc_type=regexp


Here is the list of bugs, along with my suggested target release for
each (no opinion yet, do now or never do, 2.0, 2.2 or 3.0) and
rationale. If you disagree with any of these or have an opinion where
I don't, please speak up.

If no one disagrees with any of these, that would leave us with 16
bugs definitely punted, 11 definitely on the 2.0 list, and 11 more
still to be determined.


No opinion yet (8 bugs)
--------------

* 8516 - [API] GClosure-ize everything
     Note: I'm told this is critical for binding authors but I don't
     really know the details of what it is, how to do it, or how much
     work it would be.

* 8544 - [API] add thumbnail support
     Note: I would personally make this a 2.2 item, but Lutz seems to
     want it. It will almost certainly end up 2.2 unless Lutz steps up
     to the plate with some code soon. :-)

* 8545 - [API] Add prioritized versions of all async calls
     Note: this seems like a large change with lots of new code and new
     entry points so I am not sure we should do it at all, but Laszlo
     seems very interested in adding it.

* 8451 - [API] gnome-vfs API for filesystem monitoring needs finishing
     Note: I would personally prefer to roll back the monitoring code
     as was done with metadata and do the work on a branch until it is
     ready, but Ian (the maintainer) seems to really want it in.

* 1203 - [API] GNOME_VFS_FILE_INFO_DEFAULT is not a good name
     Note: this would be really easy to change if we knew for sure we
     wanted to change it and had something to change it to.

* 7911 - [API] URI handling scheme cleanup and generalization
     Note: we have a patch for this, in the bug report, I'm just not
     sure yet if the change is a good one in principle.

* 6840 - [API] There is no way to remove a system wide application.
     Note: not sure what exactly yhis bug is asking for

* 1202 - [API] some of GnomeVFSFileInfo could be private
     Note: would be nice to make the whole struct private and use
     accessors; doable in time?

* 2801 - [API] GnomeVFSURI should handle URIs with schemes that no
module can handle

     Note: would be nice to do for 2.0, but can be done largely
     compatibly later. Perhaps this should not even be considered an
     API change if 798 is done.

Do now or never do (3 bugs)
------------------

* 1107 - [API] for clarity and "%00" handling, make all file name APIs
be URI encoded
* 1377 - [API] Reconsider URI method chaining design
* 4103 - [API] text/* is not a valid wildcard

Not sure if we should do these, but if we don't do them now, we should
probably never do them. All of these are likely to break a lot of
stuff if changed in the future (and perhaps even if changed now.


Suggested for [2.0] (11 items)
-------------------

* 8447 - [API] Authentication callback API is not threadsafe
    Rationale: this is a new API since 1.0, so we should fix it before shipping it.

* 8448 - [API] Authentication callbacks require explicit threading when using async API
    Rationale: this is a new API since 1.0, so we should fix it before shipping it.

* 8514 - [API] kill gnome-vfs-seekable
    Rationale: application authors seem to find this actively harmful more often
    than they find it helpful. Removal is relatively easy compared to
    adding. Technically incompatible so cannot be 2.2.

* 8515 - [API] kill gnome-vfs-transform
    Rationale: Nothing uses this, as far as I know. Removal is
    relatively easy compared to adding. Technically incompatible so
    cannot be 2.2.

* 8511 - [API] split public and module APIs
    Rationale: The fact that this is not done is an eyesore. It should
    be a relatively mechanical change to make and will mostly only
    affect modules.

* 8519 - [API] rename `method' to something else (`module'? `protocol'? `scheme'?)
    Rationale: simple mechanical change if we can decide on a new name.

* 8512 - [API] gnome-vfs-iobuf / gnome-vfs-socket-buffer duplication
    Rationale: mechanical change, removes unnecessary / unused API

* 8518 - [API] gnome-vfs-helpers API needs cleanup
    Rationale: This is new API since 1.0 and it's messy in various ways.
    We really should clean it up before releasing it.

* 8517 - [API] kill back end API since we only have one back end now
and it doesn't need to be a module any more

    Rationale: removing the backend API from the installed headers
    should definitely be done for the 2.0 API freeze. Removing
    internal use of the backed API can be punted til after the freeze.

*  798 - [API] API inconsistent about GnomeVFSURI * vs. char *
    Rationale: We really should kick GnomeVFSURI out of the public
    interface. This seems pretty doable.

* 1086 - [API] GnomeVFSURI path functions need better names, comments
    Rationale: Current situation is a mess, once we pick some good names
    this change is easy and almost mechanical 


Suggested for [2.2] (11 items)
-------------------

*  870 - [API] Many calls have sync. versions only, no async. versions.
    Rationale: Compatible change, so it can be made later; no time to
    do it for 2.0.

* 4554 - [API] GNOME-VFS symlinks need to support cross-scheme symlinks
    Rationale: We might be able to do this compatibly, and it is a lot of
    work requiring careful new design. Seth also thinks this is not a 2.0
    item.

*  799 - [API] No fast way to count directory items
    Rationale: This would indeed be nice, but it can clearly be done
    in a compatible way, and there isn't much time to do this whole
    new feature for 2.0.

* 8506 - [API] URI schemes want to specify icon, default application, etc
    Rationale: I would really like to see this for 2.0 but it's just too
    much work to do in the time allotted. Can be added compatibly however.

* 8507 - [API] it should be possible to do http POSTs
    Rationale: Probably can be done compat, no one seems to be stepping up
    to the plate to do it for 2.0

* 8509 - [API] http redirects should be supported
    Rationale: Probably can be done compat, but it's a fair amount of work that
    no one seems to be doing.

* 8508 - [API] change module stacking interface to enable proper moniker support
    Rationale: too much work for 2.0; hopefully we can find a
    compatible way to do it, especially given module versioning (I'm
    imagining an open_chained or open_stacked call in the module
    operations struct).

* 6483 - [API] gnome-vfs should standardize removable device detection, access and naming
   Rationale: can probably be added compatibly, but involves new API and is not
   really crucial for 2.0

* 1198 - [API] Should have a context for file methods to allow setting a prefix
   Rationale: can probably be added compatibly, but involves new API and is not
   really crucial for 2.0

* 8513 - [API] buffered I/O API
   Rationale: can probably be added compatibly, but involves new API and is not
   really crucial for 2.0. Also, would probably be a bunch of new code.

*  458 - [API] Indicate whether a file operation can succeed.
   Rationale: seems unlikely anyone will do this for 2.0, even though
   it would be quite useful for many things.

Suggested for [3.0] (5 items)
-------------------

* 8510 - [API] make xfer API less confusing
    Rationale: Likely incompatible, but no way this can be done in
    time for 2.0.

* 1192 - [API] progress callbacks need a cleaner set of return values
    Rationale: Incompatible change but I just don't see this happening
    for 2.0.

* 1206 - [API] GnomeVFSXferProgressInfo has fields source_name and target_name that hold URI strings
    Rationale: incompatible but does not seem like an important change

*  837 - [API] gnome_vfs_async_xfer returns a result unlike other async. ops
    Rationale: I don't think anyone is going to do work on fixing up
    the xfer API for 2.0
 
* 1205 - [API] separate xfer options and xfer actions
    Rationale: I don't think anyone is going to do work on fixing up
    the xfer API for 2.0