Merge pull request #279 from apenney/fix-spacing

[puppet-modules/puppetlabs-apt.git] / README.md

diff --git a/README.md b/README.md
index 138bfa496f05b05a6ee3bcc12847c448ceac4193..20c465dbfa1eec47e5ef0ccdfc21609635c8554b 100644 (file)
--- a/README.md
+++ b/README.md
@@ -215,6 +215,27 @@ If you would like to configure your system so the source is the Puppet Labs APT
       key_server => 'pgp.mit.edu',
     }
 
+
+#### Hiera example
+<pre>
+apt::sources:
+  'debian_unstable':
+      location: 'http://debian.mirror.iweb.ca/debian/'
+      release: 'unstable'
+      repos: 'main contrib non-free'
+      required_packages: 'debian-keyring debian-archive-keyring'
+      key: '55BE302B'
+      key_server: 'subkeys.pgp.net'
+      pin: '-10'
+      include_src: 'true'
+
+  'puppetlabs':
+      location: 'http://apt.puppetlabs.com'
+      repos: 'main'
+      key: '4BD6EC30'
+      key_server: 'pgp.mit.edu'
+</pre>
+
 ### Testing
 
 The APT module is mostly a collection of defined resource types, which provide reusable logic that can be leveraged to manage APT. It does provide smoke tests for testing functionality on a target system, as well as spec tests for checking a compiled catalog against an expected set of resources.
@@ -252,6 +273,10 @@ Implementation
 
 Adds the necessary components to get backports for Ubuntu and Debian. The release name defaults to `$lsbdistcodename`. Setting this manually can cause undefined behavior (read: universe exploding).
 
+By default this class drops a Pin-file for Backports pinning it to a priority of 200, lower than the normal Debian archive which gets a priority of 500 to ensure your packages with `ensure => latest` don't get magically upgraded from Backports without your explicit say-so.
+
+If you raise the priority through the `pin_priority` parameter to *500*, identical to the rest of the Debian mirrors, normal policy goes into effect and the newest version wins/becomes the candidate apt will want to install or upgrade to. This means that if a package is available from Backports it and its dependencies will be pulled in from Backports unless you explicitly set the `ensure` attribute of the `package` resource to `installed`/`present` or a specific version.
+
 Limitations
 -----------
 
@@ -282,6 +307,7 @@ A lot of great people have contributed to this module. A somewhat current list f
 * Branan Purvine-Riley <branan@puppetlabs.com>
 * Christian G. Warden <cwarden@xerus.org>
 * Dan Bode <bodepd@gmail.com> <dan@puppetlabs.com>
+* Daniel Tremblay <github@danieltremblay.ca>
 * Garrett Honeycutt <github@garretthoneycutt.com>
 * Jeff Wallace <jeff@evolvingweb.ca> <jeff@tjwallace.ca>
 * Ken Barber <ken@bob.sh>