* '''Launchpad entry:''' https://blueprints.edge.launchpad.net/launchpad/+spec/pillar-alias
 * '''Created:''' <<Date(2007-12-07T21:26:33Z)>> by FrancisJLacoste 
 * '''Contributors:''' 

== Summary ==

We want to add aliases to our pillars. To achieve this, we'll add an 'aliases'
column on our pillars tables: `Distribution`, `Product`, `Project`. Launchpad
administrators will be able to modify that field, and triggers will maintain
automatically the `PillarName` table.

== Release Note ==

Launchpad now supports project aliases. If one of your project is well known
on another alias, file a question on the Launchpad project stating your
project and the aliases you'd like. 

== Rationale ==

Some projects are known under many names. Restricting projects to only one
name makes users register project on the other names. This would also be
useful for migration purpose.

== Use cases ==

 * The Gaim was renamed to Pidgin. Its maintainer renames his project from
 'gaim' to 'pidgin' and asks that an alias for 'gaim' be maintained.
 * Many users tries to register the 'postgres' project. That project is
 already registered under 'postgresql'. A Launchpad administrator adds the
 common 'postgres' alias to this project.

== Assumptions ==

We are not doing automatic alias creation on renaming because the main use-case 
for allowing project renaming is to free up the namespace.

== Design ==

Since our namespace is maintained in the `PillarName`, aliases need to appear in
that table. Since this table is automatically maintained using trigger, it
makes sense that the aliases are also added automatically based on an aliases
column in the distribution, project, and product tables.

Since aliases could cause land-grab abuses, modifying the aliases of a project
will be restricted to Launchpad administrators.

This is only to make aliases work on the web app; we need to do
changes in other places to make it possible for bzr to
access branches using a product's alias.
After discussion with Aaron, it seems like we have two
options.

 1. Update our xmlrpc to dereference lp: URLs using a product's alias, thus giving the branch's canonical URL to bzr.

 2. Supporting the aliases on the codehosting system, probably through redirects. The problem, though, as pointed by Aaron is that doing redirects properly for bzr+ssh or sftp requires a new bzr format, and work on the twisted server; improperly just requires twisted work. Either way it's some considerable work.

We decided to nor implement this in the first round.  If needed, it can obviously implemented later.

== Implementation ==

=== UI Changes  ===

Launchpad administrators visiting the 'Edit details' page of distributions,
products and projects will see a simple text field called 'Aliases'. 

=== Code Changes ===

We'll need to modify the Launchpad navigation to redirect to the base pillar
name if a URL uses an alias. This can be done simply using:

    {{{
    # Pillar accessed through one of its aliases
    if pillar.name != name:
        self.redirectSubTree(canonical_url(pillar), status=301)

}}}

The `PillarNameSet.search()` method will also need to be modified so that the
aliases are considered for exact name matching.

`Branch` navigation will also need to do this redirection.

We'll add a `getCanonicalName()` to `IPillarName`. That method will return the
canonical name or self if called on the canonical one.

We may add a `getCanonical()` method on `IPillarName` which
would retrieve the canonical `PillarName` or self, when it's the
canonical one.

==== IPillar ====

A new `IPillar` will be defined. It will provide the following attributes:

    {{{

    class IPillar(Interface):
    
        name = PillarNameField(
            title = _('Name'),
            description=_('The pillar canonical name.'),
            constraint=name_validator,
            required=True, readonly=True)
        
        aliases = Attribute('Sequence of aliases name for this pillar.')

        def addAlias(name):
            """Adds an alias to this pillar.

            :raises AliasAlreadyDefinedError: if the name is already taken.
            """

        def removeAlias(name):
            """Removes an alias from this pillar.

            :raises NotFoundError: if the alias isn't defined.
            """
}}}

=== UI Changes ===

A field to edit the aliases will be added to the 'Edit details' of 
distribution, project and product. That field will be a simple text field
containing a white-space delimited list of aliases name. Editing of that field
will be restricted to Launchpad administrators.

=== Schema Changes ===

We'll add an `alias` column to the `PillarName` name.

    {{{
ALTER TABLE PillarName ADD COLUMN alias_for integer;
ALTER TABLE PillarName ADD CONSTRAINT pillarname__alias_for__fk
    FOREIGN KEY (alias_for) REFERENCES PillarName;
CREATE INDEX pillarname__alias_for__idx ON PillarName(alias_for)
    WHERE alias_for IS NOT NULL;

ALTER TABLE PillarName DROP CONSTRAINT only_one_target;

}}}

We'll need to drop the constraint on `PillarName` that only one
name exists for each pillar (distribution, product, project).

The trigger will also need to be modified to cope with the fact that more than 
one pillarname may be associated with a pillar. What trigger? ElliotMurphy

=== Migration ===

No migration is necessary.