Notes on build reproducibility of Debian packages
=================================================

This repository contains notes concerning the status of build
reproducibility of Debian packages.

There are two files:
- issues.yaml which contains all the categorized issues
- packages.yaml which contains notes about issues in packages

There is another repository, ssh://git.debian.org/git/reproducible/misc.git
which contains some scripts to deal with the YAML files in notes.git though
usually one uses any text editor to edit those two files and commit them.

We very much welcome patches to notes.git via email to
reproducible-builds@lists.alioth.debian.org - and please apply to become
a member of the reproducible project on salsa.debian.org if you plan to contribute
regularily!


Description of the YAML format used in the two files:

`packages.yml`
--------------

`packages.yml` is a YAML file with notes about debian source packages.

A full entry looks like the following:

    socat:
      version: 1.7.2.4-1
      comments: |
        Patch submitted.
      issues:
        - timestamps_from_cpp_macros
      bugs:
        - 764251

Every field is optional, although a version number would be useful to do
cleanups.

 - `version`: is the earliest Debian version number of the examined source package, usually the one in unstable.

 - `issues`: is a list of tags as described in the `issues.yml` file.

 - `bugs`: is a list of Debian bug numbers reported about the package.

 - `comments`: is a free-form multi-line field to leave comments.

If an issue for the package has been fixed in sid, it should be removed from `packages.yml`.

`issues.yml`
------------

`issues.yml` is a YAML file with a description of common issues.

A full entry looks like the following:

    timestamps_from_cpp_macros:
      description: |
        The C pre-processor macros `__DATE__`, `__TIME__`, and `__TIMESTAMP__`
        capture the current time, and thus will obviously make a build
        unreproducible.
      url: https://wiki.debian.org/ReproducibleBuilds/TimestampFromCPPMacros

The name of the issue should contain underscores instead of hyphens as
text editor autocompletion works better with the former.

 - `description`:  is a mandatory free-form multi-line description of the issue.

 - `url`: is an optional field pointer to a page (ideally on the Debian wiki)
    describing the issue in more details.

 - `deterministic` (default False): is an optional field indicating whether
    we expect that this issue would always happen on Jenkins; i.e. if
    there is a successful build, then the issue is fixed for that package.

Arch Linux
----------

Classifications for Arch Linux packages are currently tracked here:

https://gitlab.archlinux.org/archlinux/reproducible-archlinux-notes

Machine-readable data is available here:

https://reproducible-notes.archlinux.org/packages.json