= Creating a new data source =

Any Debian Developer can create and manage data sources. To do so, login into [[http://contributors.debian.org]] using your [[DebianSingleSignOn|web password]].

Once you are logged in, you can go to [[https://contributors.debian.org/source/|Data Sources]] details and see "Edit" links and a "Create new data source" link. The editing forms are meant to document themselves, please [[http://bugs.debian.org/nm.debian.org|report a bug]] if they are still not clear.

For each data source you need to configure one of more contribution types, to define the various types of contributors that you have in your team.

= Implementation notes =

If you are implementing a data source in Python, you may want to ignore the details outlined below, and instead use the DebianPkg:python3-debiancontributors package instead.

== JSON structure of a submission ==

A submission is an array of {{{Record}}}s:
{{{
Submission := [ Record ]
}}}

A {{{Record}}} is an object with the identity of the contributor and a list of contributions:
{{{
Record := { id: [ Identifier ], contributions: [ Contribution ] }
}}}

There can be more than one {{{Identifier}}} per {{{Record}}}, but there usually is only one. There can be one or more {{{Contribution}}} per {{{Record}}}.

An {{{Identifier}}} is an object identifying the contributor in one of many possible ways:
{{{
Identifier := { type: IdentifierType, id: string, desc: optional_string }

IdentifierType := "login"|"email"|"fpr"
}}}

 * {{{type}}} is the type of identifier. Currently only debian.org or alioth login names, emails and OpenPGP key fingerprints are supported.
 * {{{id}}} is the actual identifier, which could be a username, an email address, or an OpenPGP key fingerprint without any spaces.
 * {{{desc}}} is a human-readable version for the identifier, like a person's full name, if available.

A {{{Contribution}}} is an object detailing one kind of contribution over time:
{{{
Contribution := { type: string, begin: optional_Date, end: optional_Date, url: optional_string }

Date := "yyyy-mm-dd"
}}}

 * {{{type}}} is the string configured as a contribution type name in the source configuration on contributors.debian.org
 * {{{begin}}} is when one started contributing. If missing, the server will use the previously reported begin date. If no previous contribution has been seem, the server will use today's date.
 * {{{end}}} is the time of the last known contribution. If missing, the server will use today's date.
 * {{{url}}} is a URL pointing to a page that will list details of this kind of contributions for this person, if available. If missing, the server will just render the contribution details with plain text instead of a hyperlink.

=== Examples ===

A minimal submission:
{{{
[
  { "id": [ { "type": "login", "id": "enrico" } ],
    "contributions": [
      { "type": "talking" }
    ]
  },
  { "id": [ { "type": "login", "id": "93sam" } ],
    "contributions": [
      { "type": "talking" }
    ]
  }
]
}}}

An even more minimal submission: list of only one {{{Identifier}}} or {{{Contribution}}} can be replaced by the single object:
{{{
[
  { "id": { "type": "login", "id": "enrico" },
    "contributions": { "type": "talking" } },
  { "id": { "type": "login", "id": "93sam" },
    "contributions": { "type": "talking" } }
]
}}}

A more detailed submission:
{{{
[
  { "id": [ { "type": "login", "id": "enrico" } ],
    "contributions": [
      { "type": "talking", "begin": "2010-01-01", "end": "2013-11-16",
        "url": "http://talks.debian.org/enrico"
      }
    ]
  },
  { "id": [ { "type": "login", "id": "93sam" } ],
    "contributions": [
      { "type": "talking", "begin": "1990-05-01", "end": "2013-11-16",
        "url": "http://talks.debian.org/93sam"
      }
    ]
  }
]
}}}

== Posting a submission ==

Submission are sent via a {{{multipart/form-data}}} HTTP POST to {{{https://contributors.debian.org/contributors/post}}}

The JSON data is sent as a file field called 'data', so you will need an HTTP client capable of file uploads.

The other fields uploaded are:

 * {{{source}}} is the source name as configured in the site
 * {{{auth_token}}} is the authentication token configured in the site
 * {{{data_compression}}} (optional) is the data compression used for the JSON data (by default, no compression; {{{gzip}}} and {{{xz}}} are supported.
 * {{{method}}} (optional, default: 'replace', valid values: 'replace', 'extend') changes the way submitted contributions are merged with existing ones. See 'Submission methods' below.


=== Submission methods ===

There are two ways in which submitted contributions are merged with existing ones on the site: 'replace' (the default' and 'extend').

In both cases, a missing end date in the contribution period is always taken as today's date.

==== Replace ====

When the 'begin' time is present, it always replaces the existing value in the database. The 'end' time always replaces the existing value in the database.

==== Extend ====

When the 'begin' time is present, it replaces the existing value in the database only if it is an earlier date.

The 'end' time replaces the existing value in the database only if it is a later date.


=== Examples ===

Submission, with compression:
{{{
curl https://contributors.debian.org/contributors/post \
     -F source="Debian Talkers" -F auth_token="foobarbaz1234" \
     -F data_compression=gzip -F data=@filename.json.gz
}}}

Plain submission:
{{{
curl https://contributors.debian.org/contributors/post \
     -F source="Debian Talkers" -F auth_token="foobarbaz1234" \
     -F data=@filename.json
}}}

== Helping the project ==

If you want to help, see the [[Teams/FrontDesk/DcSiteDevel|todo-list page]].
If you like to work with Python and Django, this can be a very good way to get more involved in Debian.

== References ==

All the related documentation (articles, talks, etc) about Debian Contributors should be in the [[DebianContributors/DcDocs|docs]] page.


These links are more or less directly related to what could be going on here:
 * [[http://www.enricozini.org/2012/debian/more-diversity-in-skills/|Making Debian diversity visible]]
 * [[http://www.ted.com/talks/amanda_palmer_the_art_of_asking.html|Amanda Palmer's The Art of Asking TED talk]]
 * [[http://www.ted.com/talks/chimamanda_adichie_the_danger_of_a_single_story.html|Chimamanda Adichie's The Danger of a Single Story TED talk]]