Title: Per-package machine-readable metadata about Upstream
DEP: 12
State: DRAFT
Date: 2014-02-23
Drivers: Charles Plessy <plessy@debian.org>,
  Andreas Tille <tille@debian.org>
  Jelmer Vernooij <jelmer@debian.org>
URL: http://dep.debian.net/deps/dep12
Source: https://salsa.debian.org/dep-team/deps/-/blob/master/web/deps/dep12.mdwn
Abstract:
 The source package control files and some of their derivatives are currently
 used to document the URL of the home page of the work that is packaged
 ("upstream").  However, this approach is hard to extend to other information
 describing upstream, because the size of the control files has to be limited
 according to the limited power of some systems running Debian.
 .
 We propose a new file in the source packages, debian/upstream/metadata, formatted
 in YAML to hold arbitrary information about upstream, for instance the
 URL to a donation page, bibliographic information about publications
 describing the upstream work, the URL to the upstream sources, etc.
  1. Upstream Metadata Specification
    1. Introduction
    2. Purpose
    3. Fields
    4. More information
    5. License
    6. Timeline

Upstream Metadata Specification

The format of the metadata file is being developed on http://wiki.debian.org/UpstreamMetadata. Following the progress of the discussion on the debian-qa mailing list, implementation details that made consensus will be transferred here.

Introduction

The {{{debian/upstream/metadata}}} file is in http://www.yaml.org/ format. There should only be a single YAML document.

In its simplest form, the metadata file looks much like the stanza format used in Debian control files. Nevertheless, there may be sometimes unexpected behaviours, for instance field contents that have a colon inside have to be quoted in some cases. If in doubt, there are validators available, either on-line http://yaml-online-parser.appspot.com/, or in command line (DebPkg:yamllint).

Purpose

The upstream metadata file is meant to contain machine-readable metadata about the upstream project, its community and processes.

Information in this file should not be specific to Debian, and be relevant for other distributions as well.

The following upstream metadata is currently stored elsewhere in Debian control files and should not be included in debian/upstream/metadata.

When defining new fields, the same vocabulary as in http://usefulinc.com/doap should be used as much as possible.

Fields should be in in alphabetic order.

Fields

Archive:: The name of the large archive that the upstream work is part of, like CPAN.

ASCL-Id:: Identification code in the http://ascl.net

Bug-Database:: A URL to the list of known bugs for the project.

Bug-Submit:: A URL that is the place where new bug reports should be sent.

Cite-As:: The way the authors want their software be cited in publications. The value is a string which might contain a link in valid HTML syntax. (http://lists.debian.org/debian-science/2012/05/msg00008.html)

Changelog:: URL to the upstream changelog.

CPE:: One or more space separated http://cpe.mitre.org/ values useful to look up relevant CVEs in the https://nvd.nist.gov/home.cfm and other CVE sources. See CPEtagPackagesDep for information on how this information can be used. Example: "cpe:/a:ethereal_group:ethereal"

Documentation:: A URL to online documentation.

Donation:: A URL to a donation form (or instructions).

FAQ:: A URL to the online FAQ.

Funding:: One or more sources of funding which have supported this project (e.g. NSF OCI-12345).

Gallery:: A URL to a gallery of pictures made with the program (not screenshots).

Other-References:: A URL to a upstream page containing more references.

Reference:: One or more bibliographic references, represented as a mapping or sequence of mappings containing the one or more of the following keys. The values for the keys are always scalars, and the keys that correspond to standard BibTeX entries must provide the same content.

Author:: Author list in BibTeX friendly syntax (separating multiple authors by the keyword "and" and using as few as possible abbreviations in the names, as proposed in http://nwalsh.com/tex/texhelp/bibtx-23.html).

Booktitle:: Title of the book the article is published in

DOI:: This is the digital object identifier of the academic publication describing the packaged work.

Editor:: Editor of the book the article is published in

Eprint:: Hyperlink to the PDF file of the article.

ISBN:: International Standard Book Number of the book if the article is part of the book or the reference is a book

ISSN:: International Standard Serial Number of the periodical publication if the article is part of a series

Journal:: Abbreviated journal name [To be discussed: which standard to recommend ?].

Number:: Issue number.

Pages:: Article page number(s). [To be discussed] Page number separator must be a single ASCII hyphen. What do we do with condensed notations like 401-10 ?

PMID:: ID number in the https://www.ncbi.nlm.nih.gov/pubmed/ database.

Publisher:: Publisher of the book containing the article

Title:: Article title.

Type:: A http://www.bibtex.org/Format indicating what is cited. Typical values are {{{article}}}, {{{book}}}, or {{{inproceedings}}}. [To be discussed]. In case this field is not present, {{{article}}} is assumed.

URL:: Hyperlink to the abstract of the article. This should not point to the full version because this is specified by Eprint. Please also do not drop links to pubmed here because this would be redundant to PMID.

Volume:: Journal volume.

Year:: Year of publication

Registration:: A URL to a registration form (or instructions). This could be registration of bug reporting accounts, registration for counting/contacting users etc.

Registry:: This field shall point to external catalogs/registries of software. The field features an array of "Name (of registry) - Entry (ID of software in that catalog)" pairs. The names and entries shall only be names, not complete URIs, to avoid any bias on mirrors etc. Example: {{{ Registry: - Name: bio.tools Entry: clustalw - Name: OMICtools Entry: OMICS_02562 - Name: SciCrunch Entry: SCR_002909 }}} Valid ''Name'' entries for Registry are: https://bio.tools/, https://biii.eu/, https://omictools.com/, https://scicrunch.org/, https://bioconda.github.io/, https://opam.ocaml.org/ and https://pypi.org/. Other channels of conda can be referenced analogously by their name, for instance https://conda-forge.org/ or https://anaconda.org/r, but may not yet be prepared to be interpreted. Special value of ''Entry'' {{{NA}}} means that a catalog/registry is confirmed to not have an entry for this software.

Repository:: URL to a repository containing the upstream sources.

Repository-Browse:: A URL to browse the repository containing the upstream sources.

Screenshots:: One or more URLs to upstream pages containing screenshots (not {{{screenshots.debian.net}}}), represented by a scalar or a sequence of scalars.

Security-Contact:: Which person, mailing list, forum,… to send security-related messages in the first place.

Webservice:: URL to an web page where the packaged program can also be used.

More information

See http://wiki.debian.org/UpstreamMetadata for the broader discussion about upstream metadata in Debian that this DEP is a result of.

You can find lots of examples of existing debian/upstream/metadata files using https://codesearch.debian.net/search?q=path:debian/upstream/metadata.

lintian has a preliminary check for debian/upstream/metadata files.

UDD includes a upstream_metadata table with information extracted from debian/upstream/metadata files.

upstream-ontologist has a guess-upstream-metadata command that can generate debian/upstream/metadata files.

License

This work is dedicated to the public domain, using the Creative Commons Zero (CC0) Public Domain Dedication, version 1.0

Timeline