apt/vendor/README

The vendor system in APT is an experiment to help distributions ship a stock
apt release instead of applying documentation patches to it, increasing
maintenance burden for everyone and hiding 'interesting' patches in the mix.

The provided information is used in the apt-key script and in documentation
like manpages and example configuration files. If you have patches modifying
additional bits and pieces currently not covered by this system please
contact us so we can change this!


== Adding a new vendor

In the same directory you found this README in you should create a new
directory with the name of your distribution (as defined by dpkg-vendor,
 e.g. via "dpkg-vendor --query Vendor"). The name is case-insensitive,
but ensure that the name is otherwise correct and the other fields in
your deb-origin(5) file are correct as well as our buildsystem relies on
this information.

If no information is found for the current vendor at buildtime, the system
looks for a vendor the current vendor is a derivative of, falling back to
Debian if all else fails.

The directory should include 2 files at the moment. It is best to look
at the files of other distributions to understand what values are to be
expected. Some additional notes about them can be found below.

If we happen to include new fields/files in this system, we will opt for
using a sensible default rather than failing the build or similar, so
you are recommend to watch this space.
Ensure also that your information is up-to-date!

Contributing a new vendor as well as updating a existing one is best done
by opening a bug in the Debian BTS against apt with a patch attached.


== apt-vendor.ent

The format used is the one DocBook XML uses. The file is included as an
entity file in the manpages xml source, so the syntax has to be valid!

The keyring-* settings are additionally used also in the creation of the
apt-key script and the keyring-package in particular as a dependency for apt.

The field current-codename is optional and can be used in sources.list.in.

The fields sourceslist-list-format and sourceslist-sources-format are used as
examples in the sources.list manpage and the first one is additionally
available in the sources.list.in template.
They should in general reflect the default sources of your distro.

== sources.list.in

An example for a sources.list which will be shipped in /usr/share/doc.
This file will NOT be installed in /etc or otherwise used by apt.

You can use some placeholders in this file, namely:
* &debian-stable-codename;
* &debian-oldstable-codename;
* &debian-testing-codename;
* &ubuntu-codename;
* &sourceslist-list-format;
with the value you would expect based on the name.

The placeholder &current-codename; is yours and can be set in apt-vendor.ent


== apt.conf-*

Files in your vendor directory following this naming scheme will be picked up
by the debian/rules file and installed in /etc/apt/apt.conf.d/ directory, with
"apt.conf-" removed from the beginning of the filename.