Title: Per-package machine-readable metadata about Upstream
DEP: 12
State: ACCEPTED
Date: 2014-02-23
Drivers: Charles Plessy <plessy@debian.org>,
  Andreas Tille <tille@debian.org>
  Jelmer Vernooĳ <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.

Upstream Metadata Specification

Upstream Metadata Specification

Introduction

The debian/upstream/metadata file is in YAML 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 Online YAML Parser, 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.

Homepage in the Source package or Binary stanza
Upstream-Contact / Upstream-Name in debian/copyright; as described in the machine-readable Debian copyright file

When defining new fields, the same vocabulary as in 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 Astrophysics Source Code Library
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. (see discussion on Debian Science list)
Changelog: URL to the upstream changelog.
CPE: One or more space separated Common Platform Enumerator values useful to look up relevant CVEs in the National Vulnerability database 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 PubMed database.
- Publisher: Publisher of the book containing the article
- Title: Article title.
- Type: A BibTeX entry type 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: bio.tools, biii, OMICtools, SciCrunch, conda:bioconda, opam and PyPI. Other channels of conda can be referenced analogously by their name, for instance conda:conda-forge or conda: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.

Examples

This is an example of a debian/upstream/metadata file for a package that has a lot of information about upstream:

Bug-Database: https://github.com/eradman/entr/issues
Bug-Submit: https://github.com/eradman/entr/issues/new
Changelog: https://github.com/eradman/entr/blob/master/NEWS
Documentation: https://eradman.com/entrproject/entr.1.html
Other-References: https://eradman.com/entrproject/
Repository-Browse: https://github.com/eradman/entr
Repository: https://github.com/eradman/entr.git

And here is an example of a debian/upstream/metadata file for a package that has bibliographic information about upstream, something that is common for scientific software:

ASCL-Id: 1112.019
Contact: astro-aladin@unistra.fr
Name: Aladin
Reference:
 Author: >
      Bonnarel, F. and Fernique, P. and Bienayme, O. and Egret, D.
      and Genova, F. and Louys, M. and Ochsenbein, F. and Wenger, M.
      and Bartlett, J. G.
 title: The ALADIN interactive sky atlas. A reference tool for identification of astronomical sources
 journal: Astronomy and Astrophysics Supplement Series
 year: 2000
 month: Apr
 volume: 143
 pages: 33 - 40
 URL: http://cdsads.u-strasbg.fr/abs/2000A%26AS..143...33B
 eprint: http://aas.aanda.org/articles/aas/pdf/2000/07/ds1785.pdf
 doi: 10.1051/aas:2000331

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 codesearch.debian.net.

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

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

Tools that support this DEP

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

lintian-brush will automatically update the debian/upstream/metadata file when it finds a new field in the upstream sources, using the upstream-ontologist.

git-buildpackage and breezy-debian read the Repository field from the debian/upstream/metadata file to determine the upstream source repository when import new upstream versions.

debian-json-schemas provides a JSON schema of the file format for validating the file format.

License

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

Timeline

Thu, 3 Jan 2013: announce on debian-project
Sun, 23 Feb 2014: The location of the metadata file was moved from debian/upstream to debian/upstream/metadata.
Mon, 6 Feb 2023: Migrated most of the syntax definition from the wiki to the DEP definition.
Fri, 13 March 2025: Fixed formatting issues