Contents
What is contributors.debian.org
"Debian Contributors is a website with a list of people and teams actually contributing to the Debian Project. Behind this web end, there is a software infrastructure to allow contributions data from different sources, to be automatically gathered in a standard format." from Laura Jarjona's report.
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"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.gzPlain submission:
curl https://contributors.debian.org/contributors/post \
-F source="Debian Talkers" -F auth_token="foobarbaz1234" \
-F data=@filename.json
Opting-in to contributors list
If you're a Debian Member (aka DD), you are automatically opted-in to the contributors list. Then you can associate other identifiers you might use to your user at contributors.debian.org. See the next section for details.
If you're not a Debian Member, you must create a salsa account. Salsa is a collaborative development platform within Debian and will be used to authenticate yourself in the contributors website. After your first login in contributors.debian.org, you can claim and associate identifiers to your username. See the next section for details.
Handling identifiers
The service is capable of automatically mapping a few identifiers, such as debian.org login names to email. Additionally, you can associate other identifiers to your 'person' in the system, for instance in the case you have contributed to Debian using multiple emails and multiple PGP keys.
Once logged in to contributors.debian.org, you can associate identifiers by accessing via the account menu. If you're a Debian Member, you can claim identifiers to any person in the system (always ask them first!).
Handling privacy
You can opt-out from contributors.debian.org at anytime. For that, go to your 'personal page', under the 'User visibility" section select "hide all activity from this user". You can also hide contributions from specific identifiers only.
If you want to hide your contributions made to a specific team only, go the the respective data source. You'll notice that a new item appears in menu on the top. This is the place where you can set your 'user settings' and choose not to be listed for that data source.
Why am I not on the contributors list?
If you think you should be on the Debian contributors list, but you're not (or you're on the list but some of your contributions are missing), then we can think of at least one of the following possibilities:
You haven't opted-in yet. If you are not a Debian Member (aka DD) you have to opt-in in order to be listed on the contributors list. Please check this section to find out how to proceed.
You opted-in, but you haven't associated your login account to the identifier used in your contribution (for instance, if you used another email to report a bug, or if your wiki account is not yet linked (associated) to your user in the website. Please check this section for more information.
- The team to which you contributed has not yet added a data source to feed the list of contributors. In that case, contact your team, or consider to add this new data source yourself!
- The team to which you contributed has provided a data source, but for some reason it's not feeding the contributors website. It might be out of date, broken, abandoned. In the 'data sources' section of contributors.debian.org you can see who's the data source admin and contact them to fix.
- The data source of your team requires more than one contribution in order to feed the contributors list. For instance, contributions to BTS requires at least 5 emails in order to avoid spammers being marked as contributors.
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: