summaryrefslogtreecommitdiff
path: root/vendor/README
diff options
context:
space:
mode:
Diffstat (limited to 'vendor/README')
-rw-r--r--vendor/README72
1 files changed, 72 insertions, 0 deletions
diff --git a/vendor/README b/vendor/README
new file mode 100644
index 000000000..6846c8455
--- /dev/null
+++ b/vendor/README
@@ -0,0 +1,72 @@
+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.