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 web password.

Once you are logged in, you can go to Data Sources details and see "Edit" links and a "Create new data source" link. The editing forms are meant to document themselves, please 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 python3-debiancontributors package instead.

JSON structure of a submission

A submission is an array of Records:

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"

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"

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:

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 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 docs page.

These links are more or less directly related to what could be going on here: