From 667e0dffa0ebe1a974e47173cc9be2e18ed22445 Mon Sep 17 00:00:00 2001
From: Ian Wienand <iwienand@redhat.com>
Date: Tue, 16 Jul 2019 15:52:36 +1000
Subject: [PATCH] Add some pointers on the OpenDev PPA
The OpenStack/OpenDev PPA repositories are currently undocumented.
Add some information on where to find things.
Change-Id: Iea03c5d558b3dd6af9f7c860dfcc75a71dc59d9f
---
doc/source/ppa.rst | 72 ++++++++++++++++++++++++++++++++++++++++++
doc/source/systems.rst | 1 +
2 files changed, 73 insertions(+)
create mode 100644 doc/source/ppa.rst
diff --git a/doc/source/ppa.rst b/doc/source/ppa.rst
new file mode 100644
index 0000000000..65fc18db79
--- /dev/null
+++ b/doc/source/ppa.rst
@@ -0,0 +1,72 @@
+:title: OpenDev PPA
+
+.. _opendev_ppa:
+
+OpenDev PPA details
+###################
+
+There are various utilities where the OpenDev infrastructure requires
+tools or utilities with updates, bug fixes or are otherwise not
+packaged by upstream.
+
+Since our standard server environment is Ubuntu, we utilise shared
+`PPA <https://launchpad.net/ubuntu/+ppas>`__ repositories to build and
+provide these updated packages.
+
+It is generally our intention to work with upstream to make all
+relevant changes in a generic fashion. Unfortunately the reality of
+also running production systems sometimes interferes with this goal!
+
+Any packages coming from the OpenDev PPA are therefore rather ad-hoc,
+and depend on circumstances resulting in needing a new package. Some
+will incorporate a patch or bug fix, others may back port new versions
+of software, it may be software that is not available in the upstream
+distribution for various reasons.
+
+Generally any specifics relating to the packages in the various PPA's
+under the OpenStack CI Core team's purview will be documented in the
+playbooks, roles or scripts that are using the PPA.
+
+At a Glance
+===========
+
+:Hosts:
+ * Various
+:Ansible:
+ * Various
+:Projects:
+ * https://launchpad.net/~openstack-ci-core
+
+Permissions
+===========
+
+To have permissions to create a new PPA in the ``openstack-ci-core``
+team, or work existing PPA's you need to be added as a member. Any
+current member of the team, or the parent `OpenStack Administrators
+<https://launchpad.net/~openstack-admins>`__ group can add a person to
+the PPA.
+
+This can be arranged via discussion in #openstack-infra, on the infra
+mailing list or perhaps via a topic discussion in the weekly meeting.
+
+Uploading
+=========
+
+Debian packaging can get quite complex, and you will need an
+understanding of how to create ``.deb`` packages, sign them and use
+tools to upload into the PPA. There are many various guides
+
+* http://shallowsky.com/blog/programming/packaging-launchpad-ppas.html
+* https://askubuntu.com/questions/71510/how-do-i-create-a-ppa/493577#493577
+* https://wiki.debian.org/HowToPackageForDebian
+
+Note you will have to have your GPG key in your launchpad profile, and
+upload the source packages signed with that key for them to be
+accepted and built.
+
+Usage
+=====
+
+Generally the PPA will be used in Ansible roles via the inbuilt
+``apt_repository`` task. Once the PPA is added standard install
+mechanisms are used for the package install.
diff --git a/doc/source/systems.rst b/doc/source/systems.rst
index 911c5e3fd3..7b7aebd13f 100644
--- a/doc/source/systems.rst
+++ b/doc/source/systems.rst
@@ -46,3 +46,4 @@ Major Systems
asterisk
survey
letsencrypt
+ ppa