= Affiliations =
'''Blueprint: [[https://blueprints.edge.launchpad.net/launchpad-registry/+spec/project-affiliation|Project/Team Affiliations]]'''
Launchpad has projects (née ''products'') that are a central organizing principle for open source development, bringing together bugs, code, translations, answers, etc. Projects are the seeds around which communities in Launchpad grow.
Launchpad also has teams, which are ways to organize the people who want to be
involved in a project. Teams are used in some cases to control access to
project artifacts (e.g. private bugs, code branches) and as a forum for
audiences that want to participate in the project (e.g. mailing lists).
The problem is that there is no association between people/teams and the
projects they revolve around. It can therefore often be difficult for an
interested user to find the person they need to communicate with, or the team
they want to join in order to participate more fully in a project's development.
This spec addresses this problem by introducing ''affiliations'', a way for
teams and people to be (optionally) associated with a specific project. As a
focus of discussion, please see the u/i mockup of the community structure for the Ubuntu project:
{{attachment:community_structure.png}}
== Rationale ==
How often have you gone to a project page and wondered what people or teams are related to this project? When you're looking for a way to participate, you naturally want to find the related teams and mailing lists, but this is currently fairly difficult. If the teams share a name with the project, you might get a lucky guess. Or your search might turn up something useful. Or you might be able to follow the obscure trail from various project artifacts and permissions to the people and teams controlling them. Ultimately though, because these relationships are not explicit, this is all left to luck, chance, and The Googles.
Similarly, you might have a fantastic idea for improving the user interface for a web application, or you have a branch of code that fixes an obscure bug, and you'd like to get it reviewed and merged into the project's mainline. You can usually find ''a'' person who is involved with the project, bug can you always find the ''right'' person? Maybe you want to contact the lead architect, or the user interface designer, or the documentation guru, or the BDFL. Launchpad doesn't provide a way to designate these arbitrary community-recognized roles.
Let's say you ask a question about a project and someone gives you an answer. Can you trust that answer? What if you got two conflicting answers? Which one would you put more stock in? If there were a way to identify the structure and hierarchy of a project, you might put more faith in the answer from the project's BDFL than from a user or even a developer.
Wouldn't it be nice if a project owner could link specific people and teams
with the project? Wouldn't it be nice if relationships between people/teams
and their projects could be described in terms that make sense to, and have
been agreed upon by, the project's community? Wouldn't it be nice if, on the
project page you could see a list of related people and teams, and know
exactly who was in charge of documentation, or the web site design, or wiki
gardening, or internationalization? Similarly, from a person or team's, would
you like to see a link to their related projects?
Making these relationships, which often already exist implicitly, explicit and
easily discovered opens up a new world of collaboration on Launchpad. For
users looking to participate in the project, there's much less guesswork in
finding the channels for this participation.
These relationships that people and teams can have with a project model that project's community of contributors. By allowing us to specify and describe the affiliations between people/teams and projects, we can capture arbitrary community structure without imposing a rigid semantic on this structure. We let communities self-organize, evolving from small projects with individual people in key roles, to large, complex, and mature projects with teams filling many of those same roles.
== Data model ==
To support affiliations, two key concepts (and their associated tables) are
proposed for adding to the Launchpad data model. These tables support the
optional links between people/teams and projects, and the descriptions of
these affiliations.
The first proposed table is `Affiliation`. This table contains a link
to a `Person` and a link to a `PillarName`. By linking to `PillarName` we
allow for affiliations to projects, project groups (née projects) and
distributions.
The `Affiliation` table contains a creation date for the affiliation, a
registrant, and a status (see below). It also contains a link to the
`AffiliationLabel` table.
{{{
CREATE TABLE affiliation (
id serial PRIMARY KEY,
person integer NOT NULL REFERENCES Person,
pillar_name integer NOT NULL,
label integer,
date_created timestamp WITHOUT TIME ZONE
DEFAULT (CURRENT_TIMESTAMP AT TIME ZONE 'UTC'),
status integer NOT NULL,
date_status_set timestamp WITHOUT TIME ZONE
DEFAULT (CURRENT_TIMESTAMP AT TIME ZONE 'UTC'),
registrant integer NOT NULL References Person,
CONSTRAINT affiliation__pillar_name__label__fk
FOREIGN KEY(pillar_name, label)
REFERENCES AffiliationLabel(pillar_name, id)
);
}}}
`AffiliationLabel` is the second proposed table, which contains a short label,
a longer text description, a creation date and a sort order.
{{{
CREATE TABLE affiliationlabel (
id serial PRIMARY KEY,
sort_order integer NOT NULL DEFAULT 0,
label TEXT NOT NULL,
description TEXT,
date_created timestamp WITHOUT TIME ZONE
DEFAULT (CURRENT_TIMESTAMP AT TIME ZONE 'UTC'),
-- UNIQUE constraint for Affiliation -> Label foreign key
CONSTRAINT affiliationlabel__pillar_name__id__key UNIQUE (pillar_name, id)
);
}}}
By assigning an order, we can display the affiliation descriptions in the
logical order the user wants them on a project's home page.
For example, in the Ubuntu project, you might have the following affiliation
labels and sort orders:
||'''label'''||'''description'''||'''sort order'''||
||Community Council||Group of people which determine the social policy and structure of the project||1000000||
||Technical Board||Responsible for architectural and technical decisions in Ubuntu||1000||
||Core developers||Experienced developers who work on the core packages and infrastructure of Ubuntu in "main" and "restricted"||500||
||MOTU Developers|| ||100||
||Ubuntu News|| ||90||
||Argentina `LoCo`|| ||75||
||Armenia `LoCo`|| ||75||
For another example, in the Python project you might have the following
affiliation labels and order:
||'''label'''||'''description'''||'''sort order'''||
||BDFL||Benevolent dictator for life||1000000||
||Release manager|| ||1000||
||Platform czar|| ||200||
||Documentation czar|| ||150||
||Core developer|| ||50||
On the project pages, we will display those affiliation labels in the order of decreasing priority, with alphabetical sorting for duplicates.
The `AffiliationStatus` is an enum describing the status of the affiliation.
Affiliations must be accepted by both the project owner and the person or team
owner before they can become official. The exact workflow is described below,
but for now, affiliation start out with status `PROPOSED` and can become
`APPROVED` once it is accepted by all parties.
== Stories ==
Here then are some stories for breaking down the work and estimating their
level of effort.
=== Project affiliation for teams ===
As a '''project owner'''<
>
I would like to be able to '''affiliate a team with a project'''<
>
So that it is easier for people to '''discover this relationship, and the ways they can participate in the project'''.
* Add a `Affiliation` table/interface/class as described above.
* Add a `AffiliationLabel` table/interface/class as described above.
* Add convenience methods/attributes to `IProduct` and `IPerson` for easier access to their affiliations.
* Add `AffiliationSet` interface/class for creating, deleting, and getting affiliations.
Note:
Story points: 2 (though with the additional scope, probably at least a 3 or 5)
=== View project affiliation ===
As a '''Launchpad user'''<
>
I would like to be able to '''view the project affiliations for a team'''<
>
So that I can more easily '''decide how I want to participate in the project.'''
* On the person/team index page, add a section show all of their affiliations, along with the descriptions, grouped alphabetically by project.
* On the project index page, add a section listing all the people/teams that are affiliated with the project along with the affiliation descriptions, in the specified order.
Notes:
* Sub-teams do not show up as affiliated even when their super team is affiliated.
Story points: 2 (though with additional scope, probably a 3 or 5)
=== Add affiliation ===
As a '''project owner'''<
>
I would like to be able to '''propose a person or team affiliation'''<
>
So that I can '''more clearly communicate to users what these relationships
are.'''
* When a project owner visits any person/team page, they see an action called
''Affiliate with project''. Clicking on this action takes them to a page with
a pull down menu containing a list of all the projects they own. They can
then propose an affiliation of the team to one of their projects.
* If the project owner is also the person or team owner, the affiliation is immediately accepted.
* If the project owner is not the person or team owner, an email message is sent to the person or team owner informing them of the proposed affiliation. While this proposal is pending, the affiliation will not show up on the project page's affiliations list.
* The person or team owner can click on the link in their email to accept or reject the affiliation proposal. If accepted, the affiliation is made ''official''. If rejected, then the affiliation is removed and it's as if it was never made.
Notes:
* Should it be possible to create this link from the project page?
* I think browsing the site to make affiliations is wrong. We do not use this pattern anywhere, and I don't think we should introduce it. User have a lot of clicks to make that happen. The smart ones will search the site, and to save time and view the +affiliations page in another window to see what happened. the right thing to do is to let the user add affiliations to the +affiliations page:
* Visit the +affiliations page.
* View the current affiliations.
* Choose add to select an existing role or generic role and pick a person or team from the picker.
* Choose the trash icon to remove a team from +affiliation.
Story points: 5
== Remove affiliation ==
As a '''project or team owner'''<
>
I would like to be able to '''break an affiliation'''<
>
So that '''it is clear there is no longer a relationship between the person/team and the project'''.
* A project owner can go to a person/team page to break that team's affiliation with the project. In this case, the affiliation is immediately removed and an email notification is sent to the person or team owner (if the project owner is not also the person or team owner).
* A person or team owner can go to their page to break the affiliation with
the project. In this case, if the team owner is also the project owner then
of course the affiliation is removed immediately. If not, then the
affiliation is made ''unofficial'' and an email notification is sent to the
project owner.
Notes:
* You must break an existing affiliation before you can reassign it.
* While a team might be able to break it's affiliation from a ~/team/+affiliation page, the project should do all the operations from its +affiliations page. The project shoudl eb working form its context, its pages, which is natural for the project.
== Notes ==
* Need an `official` boolean to describe affiliations that speak officially for a project.
* Display community structure at scale including periphery
* [[http://www.xfce.org/about/credits||xfce example]] - nesting (one level or multiple?)
* MS: free form +1
* add wizard in GuidedProjectRegistration
* martin to update mockups
* adapter based hook to extend to other applications