launchpad-reviewers team mailing list archive

[Colin Watson <mp+427502@xxxxxxxxxxxxxxxxxx>]

Colin Watson has proposed merging ~cjwatson/launchpad:redistribute-faq into launchpad:master.

Commit message:
Remove FAQ and redistribute its contents

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~cjwatson/launchpad/+git/launchpad/+merge/427502

Daniele Procida's opinion was that FAQs are an antipattern in documentation, essentially (I think) because they tend not to actually be what's frequently asked.  It would make more sense to distribute the material here into other relevant pages anyway, so do so.

I omitted "What version of Python is required?" entirely, since that's already covered near the top of `doc/how-to/running.rst`.
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~cjwatson/launchpad:redistribute-faq into launchpad:master.

diff --git a/doc/explanation/index.rst b/doc/explanation/index.rst
index c6b72d0..9b66e6d 100644
--- a/doc/explanation/index.rst
+++ b/doc/explanation/index.rst
@@ -9,6 +9,7 @@ Explanation
    running-details
    framework
    navigating
+   postgresql
    architecture
    pip
    favicon
diff --git a/doc/explanation/navigating.rst b/doc/explanation/navigating.rst
index 277d452..7b77ac5 100644
--- a/doc/explanation/navigating.rst
+++ b/doc/explanation/navigating.rst
@@ -65,3 +65,11 @@ of the ones that come up from time to time.
 
 ``zcml/``
     Various configuration files for the Zope services.
+
+Can I look at the code without downloading it all?
+==================================================
+
+Yes, you can browse the `source code
+<https://git.launchpad.net/launchpad/tree>`_ on Launchpad.  You can also use
+``git clone https://git.launchpad.net/launchpad`` to download the code
+without setting up a development environment.
diff --git a/doc/faq.rst b/doc/explanation/postgresql.rst
similarity index 52%
rename from doc/faq.rst
rename to doc/explanation/postgresql.rst
index cc7a6a7..1a4224e 100644
--- a/doc/faq.rst
+++ b/doc/explanation/postgresql.rst
@@ -1,12 +1,6 @@
-==========================
-Frequently Asked Questions
-==========================
-
-Are there Launchpad packages available?
-=======================================
-
-No, Launchpad is not packaged and there are no plans to do so.  Launchpad
-deployment is done straight from Git branches and is quite complex.
+========================
+PostgreSQL and Launchpad
+========================
 
 Why PostgreSQL?
 ===============
@@ -29,32 +23,3 @@ Highly. We make use of PostgreSQL specific features, such as:
 * Transactional DDL
 * tsearch2 full text search
 * Database permissions
-
-What version of Python is required?
-===================================
-
-Currently, Python 3.5.
-
-Can I look at the code without downloading it all?
-==================================================
-
-Yes, you can browse the `source code
-<https://git.launchpad.net/launchpad/tree>`_ on Launchpad.  You can also use
-``git clone https://git.launchpad.net/launchpad`` to download the code
-without setting up a development environment.
-
-I have Launchpad running but mails are not sent...
-==================================================
-
-Development Launchpads don't send email to the outside world, for obvious
-reasons.  They connect to the local SMTP server and send to root.  To create
-new users, create a new account and check the local mailbox, or see
-:doc:`how-to/new-user`.
-
-My database permissions keep getting deleted!
-=============================================
-
-If your local account is called "launchpad" it conflicts with a role called
-"launchpad" which is defined in ``database/schema/security.cfg``.  You need
-to rename your local account and re-assign it superuser permissions as the
-``utilities/launchpad-database-setup`` script does.
diff --git a/doc/explanation/running-details.rst b/doc/explanation/running-details.rst
index aad600b..27925ce 100644
--- a/doc/explanation/running-details.rst
+++ b/doc/explanation/running-details.rst
@@ -55,3 +55,11 @@ Get the code:
     $ utilities/update-sourcecode
     $ git clone --depth=1 https://git.launchpad.net/lp-source-dependencies download-cache
     $ make
+
+Are there Launchpad packages available?
+---------------------------------------
+
+No, Launchpad is not packaged as a ``.deb`` or a snap or anything like that,
+and there are no plans to do so.  Launchpad deployment is done straight from
+Git branches.  We don't want to increase complexity further by adding a
+packaging method that we wouldn't use ourselves.
diff --git a/doc/how-to/running.rst b/doc/how-to/running.rst
index affb999..359cb14 100644
--- a/doc/how-to/running.rst
+++ b/doc/how-to/running.rst
@@ -76,7 +76,9 @@ installed and configured on your network.
 1. If you haven't done so already, run this script to set up LXD to let you
    use your home directory inside the container.  Some developers prefer to
    only mount a subdirectory of their home directory in the container: to do
-   that, replace ``$HOME`` with ``$HOME/src`` or similar.
+   that, replace ``$HOME`` with ``$HOME/src`` or similar.  Although it may
+   be tempting, make sure not to call your local user "launchpad", as
+   :ref:`that will break <database-permissions>`.
 
 .. code-block:: sh
 
@@ -347,6 +349,9 @@ Or you can be at a prompt in the same directory and run this:
 Troubleshooting
 ===============
 
+Network connectivity
+--------------------
+
 "The LXC container is not getting an IPv4 address assigned and the network
 connectivity inside the container doesn't work."
 
@@ -363,3 +368,25 @@ the bridge interface on your computer):
 
     sudo ufw allow in on lxdbr0
     sudo ufw route allow in on lxdbr0
+
+Email
+-----
+
+"I have Launchpad running but emails are not sent."
+
+Development Launchpads don't send email to the outside world, for obvious
+reasons.  They connect to the local SMTP server and send to root.  To create
+new users, create a new account and check the local mailbox, or see
+:doc:`new-user`.
+
+.. _database-permissions:
+
+Database permissions
+--------------------
+
+"My database permissions keep getting deleted!"
+
+If your local account is called "launchpad" it conflicts with a role called
+"launchpad" which is defined in ``database/schema/security.cfg``.  You need
+to rename your local account and re-assign it superuser permissions as the
+``utilities/launchpad-database-setup`` script does.
diff --git a/doc/index.rst b/doc/index.rst
index 2eb87a4..bab273e 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -41,8 +41,6 @@ Overview
      - How do Launchpad's features fit together?
    * - :doc:`values`
      - Guidelines for designing Launchpad
-   * - :doc:`faq`
-     -
    * - :doc:`historical`
      -
 
diff --git a/doc/overview.rst b/doc/overview.rst
index 12a41dc..fc41b9d 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -9,5 +9,4 @@ Overview
    strategy
    scope
    values
-   faq
    historical