FIXME this is old and does not reflect namespaces

on port specs, a name is now of the form

package_identifier:module_name

this means that ":" is no longer allowed on module names.

--------------------------------------------------------------------------------

A package has three "names" associated with it:

- A human-readable name, which is given by the package creator, and is
  available as the 'name' attribute in the package. 
- A unique identifier, which is given by the package creator, and is
  available as the 'identifier' attribute in the package
- A code-path, which is currently given by the package user, and is
  used by the package manager to get to the package.

These three names are necessary for different reasons. A code-path
needs to be unique within a VisTrails install so that __import__ is
well-defined. However, it is not currently under the control of the
package creator. This is the main identifier for
core/packagemanager.py, which deals mainly with the executable code
aspects of VisTrails packages. A human-readable name is necessary for
the Module Palette in the UI, so that users can quickly see a
descriptive name for a package. These names might be duplicate across
a VisTrails install, and they are only cosmetic. A unique identifier
is necessary for the module registry to distinguish between
possibly conflicting module names. These are unique across _all_
VisTrails installs, so users should take extra caution to find unique
names.

--------------------------------------------------------------------------------
(The following is not going to be done until 2.0)

So I'm trying to design the packaging system to be reasonably future-proof.
Here are a few use cases I see:


Naming

Use case: You write a package with a module having a certain name. I write a
package with a module having the same name. VisTrails should handle both of
them gracefully.

Decision: We will assume a package prefix that is unique among all packages
("... in the universe"), and educate them to create these correctly. For
example, packages coming from our group should have an identifier
"edu.utah.sci.vgc.package_name".


Versioning

Use case: I write a package and decide to change its interface. I release a
new version of the package, which breaks compatibility with the old package.
VisTrails should realize this and let the user know about obsolete packages,
vistrail/package mismatches, etc.

Decision: We will allow users to specify the version of a package. Packages
will have a major.minor.release versioning scheme with specific assumed
semantics. Major versions will be generally considered to break interfaces.
Changes in minor versions will have to be fully type-compatible with the
previous version. For example, version 1.1.0 can only change execution
behavior, add new ports to modules, or add new modules. Everything else must
be exactly like 1.0.0. Between 1.1.0 and 1.1.1 there can only be changes in
execution behavior, documentation, etc: The types must be identical.

Later on (post 1.0), packages can provide meta-information on how to
automatically upgrade a module from one version to another, in the form of
rewrite rules.


Repositories

When we have the online repository of packages (post 1.0), the repository will
be able to check for the validity of the typing rules for major and minor
versions. We should also design the repositories to be distributed. We should
hold the central one, but we should assume people will eventually want to run
their own package repositories.


Can you guys think of anything?
Thanks!
-carlos

--------------------------------------------------------------------------------

Required changes for the new packaging system:

--------------------------------------------------------------------------------

If a package wants to be notified of a missing module, it should
simply implement a function called "handle_missing_module" that takes
the name and the namespace of a module that's missing. This function
should then add the right module (or modules) to the registry. This
allows configuring some packages (like webservices) to be much less
annoying.

