add a README for vendor information

1 files changed, 60 insertions, 0 deletions

diff --git a/vendor/README b/vendor/README
new file mode 100644
index 000000000..19cda6236
--- /dev/null
+++ b/vendor/README
@@ -0,0 +1,60 @@
+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.
+
+
+== 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;
+with the value you would expect based on the name.
+
+The placeholder &current-codename; is yours and can be set in apt-vendor.ent