Merge branch 'main' into ODA78-Launchpad_fix_broken_links-removed

.sphinx/spellingcheck.yaml

@@ -9,7 +9,7 @@ matrix:
     - .custom_wordlist.txt
     output: .sphinx/.wordlist.dic
   sources:
-  - _build/**/*.html|!_build/explanation/engineering-overview-translations/index.html|!_build/explanation/testing/index.html|!_build/explanation/feature-flags/index.html|!_build/explanation/launchpad-ppa/index.html|!_build/explanation/branches/index.html|!_build/explanation/code/index.html|!_build/explanation/security-policy/index.html|!_build/explanation/database-performance/index.html|!_build/explanation/url-traversal/index.html|!_build/explanation/navigation-menus/index.html|!_build/explanation/storm-migration-guide/index.html|!_build/explanation/mail/index.html|!_build/explanation/javascript-buildsystem/index.html|!_build/explanation/javascript-integration-testing/index.html
+  - _build/**/*.html
   pipeline:
   - pyspelling.filters.html:
       comments: false

custom_conf.py

@@ -129,14 +129,10 @@
     '/Background', 
     '/Concepts',  # needs update
     '/HowToUseCodehostingLocally',  # needs update
-    '/Loggerhead',  # needs update
     'Database/TableRenamePatch',  # needs update
     'Debugging#Profiling%20page%20requests',  # needs update
     'Debugging#Special%20URLs',  # needs update
     'JavascriptUnitTesting/MockIo',  # needs update
-    'Soyuz',  # needs update
-    'UI/CssSprites',  # needs update
-    'attachment:codehosting.png',  # needs update
     'https://git.launchpad.net/launchpad-mojo-specs/tree/mojo-lp-git/services',  # private
     'https://wiki.canonical.com/InformationInfrastructure/OSA/LaunchpadProductionStatus',  # private
     'https://wiki.canonical.com/Launchpad/PolicyandProcess/ProductionChange',  # private
@@ -145,6 +141,7 @@
     'irc.libera.chat',  # this is not an HTTP link
     r'https://github\.com/canonical/fetch-service*',  # private
     r'https://github\.com/canonical/fetch-operator*',  # private
+    'https://git.launchpad.net/charm-launchpad-buildd-image-modifier/tree/files/scripts/setup-ppa-buildd',  # private
     ]
 
 # Pages on which to ignore anchors

explanation/branches.rst

@@ -54,9 +54,9 @@ It is also possible to submit directly to the **db-devel** branch.
 Let's Try That in Words
 -----------------------
 
-Database changes can be destabilizing to other work, so we isolate them
+Database changes can be destabilising to other work, so we isolate them
 out into a separate branch (**db-devel**). Then there are two arenas for
-stabilizing changes for deployment: **stable** (which ends up on
+stabilising changes for deployment: **stable** (which ends up on
 `qastaging <https://qastaging.launchpad.net>`__ and is fed from the
 **master** branch), and **db-stable** (which ends up on
 `staging <https://staging.launchpad.net>`__ and is fed from the
@@ -79,7 +79,7 @@ In summary:
    with **db-devel**, sent as if it came from the Launchpad list. The
    Launchpad list will be informed of merge failures, and Launchpad
    developers will collectively be responsible for correcting them.
-   (***TODO: is this some internal list? Hmmm.***)
+   (***TODO: is this some internal list?***)
 
 -  Staging runs **db-stable**; qastaging runs **stable**. We will deploy
    production DB schema changes from **db-stable**. (After a deployment,
@@ -155,8 +155,8 @@ Now create and land a merge proposal.
 FAQ
 ---
 
-Can I land a testfix before buildbot has finished a test run that has failed or will fail?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Can I land a test fix before buildbot has finished a test run that has failed or will fail?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Yes you can, and please do if appropriate, because this will mean that
 other developers will not encounter a broken tree at all.

explanation/code.rst

@@ -13,23 +13,23 @@ system. The major sub-systems are:
 
 -  The `git` and `bzr` / `brz` clients (neither of which is part of
    Launchpad, but their behaviours are important to us)
--  Connectivity to Launchpad (git, git+ssh, and https for Git; sftp and
+-  Connectivity to Launchpad (git, git+ssh, and https for Git; SFTP and
    bzr+ssh for Bazaar)
 -  Hosting infrastructure
 -  The underlying object model
 -  The web application
 -  Email processing
 -  Code imports (from CVS, Subversion, git and Mercurial)
 -  Branch source code browser (`cgit <https://git.zx2c4.com/cgit/>`__
-   for Git; `loggerhead </Loggerhead>`__ for Bazaar)
+   for Git; :doc:`loggerhead <../how-to/land-update-for-loggerhead>` for Bazaar)
 -  Source package recipes (`git-build-recipe`/`bzr-builder\` integration
-   with `Soyuz <Soyuz>`__)
+   with :doc:`Soyuz ../how-to/use-soyuz-locally`)
 
 Each of these subsystems also have multiple moving parts and some have
 other asynchronous jobs associated with them.
 
-The `codehosting overview diagram <attachment:codehosting.png>`__
-summarizes how some of these systems interact.
+The `codehosting overview diagram :attachment:../images/codehosting.png`
+summarises how some of these systems interact.
 
 You can `run the codehosting system
 locally </HowToUseCodehostingLocally>`__.
@@ -86,14 +86,14 @@ Apache handles the HTTP routing using a number of mod-rewrite rules.
 
 '''Parts [and responsibilities] '''
 
--  HTTP apache configuration [shared with LOSAs]
+-  HTTP Apache configuration [shared with LOSAs]
 -  branch location rewrite script (called by mod-rewrite rule)
 -  ssh server
 
    -  
 
       -  authentication
-      -  sftp implementation
+      -  SFTP implementation
       -  smart server launching
 
 -  smart server
@@ -182,7 +182,7 @@ into Git repositories in Launchpad.
 
    -  
 
-      -  cscvs for CVS (and legacy Subversion imports)
+      -  CSCVS for CVS (and legacy Subversion imports)
       -  bzr-svn and subvertpy for all new Subversion imports
       -  bzr-git and dulwich for git
       -  bzr-hg for mercurial imports
@@ -192,7 +192,7 @@ Git repository source code browser (cgit)
 
 Launchpad uses `cgit <https://git.zx2c4.com/cgit/>`__ to provide a web
 view of the repository contents. We use an unmodified package of
-\`cgit`; Launchpad's customizations are in
+\`cgit`; Launchpad's customisations are in
 `turnip.pack.http <https://git.launchpad.net/turnip/tree/turnip/pack/http.py>`__.
 
 Bazaar branch source code browser (loggerhead)
@@ -208,7 +208,7 @@ branch.
 -  loggerhead itself - community project but with major contributions
    from Canonical
 
-See `Loggerhead for Launchpad developers </Loggerhead>`__ for details on
+See :doc:`Loggerhead for Launchpad developers <../how-to/land-update-for-loggerhead>` for details on
 how to land changes to Launchpad loggerhead.
 
 Source package recipes

explanation/css.rst

@@ -39,7 +39,7 @@ If you are dealing with sprites you may also have to run:
 
    make sprite_image
 
-`More info on sprites <UI/CssSprites>`__
+:doc:`More info on sprites <css-sprites>`.
 
 Fonts
 -----

explanation/database-performance.rst

@@ -88,7 +88,7 @@ can be used to do this in combination with a
 
 Be sure to clear these caches with a Storm invalidation hook, to avoid
 test suite fallout. Objects are not reused between requests on the
-appservers, so we're generally safe there. (Our storm and sqlbase
+appservers, so we're generally safe there. (Our storm and SQLBase
 classes within the Launchpad tree have these hooks, so you only need to
 manually invalidate if you are using storm directly).
 
@@ -137,7 +137,7 @@ one of these tools.
     
 
 -  StormStatementRecorder, LP_DEBUG_SQL=1, LP_DEBUG_SQL_EXTRA=1,
-   QueryCollector. In extremis you can also turn on statement logging in
+   QueryCollector. In extremes you can also turn on statement logging in
    postgresql. [Note: please add more detail if you are reading this and
    have the time and knowledge.]
 -  Raise an exception at a convenient point, to cause a real OOPS.
@@ -146,7 +146,7 @@ Efficient batching of SQL result sets: StormRangeFactory
 --------------------------------------------------------
 
 Batched result sets are rendered via the class
-canonical.launchpad.webapp.bachting.BatchNavigator. (This class is a
+canonical.launchpad.webapp.batching.BatchNavigator. (This class is a
 thin wrapper around lazr.batchnavigator.BatchNavigator.)
 
 BatchNavigator delegates the retrieval of batches from a result set to

explanation/engineering-overview-translations.rst

@@ -28,7 +28,7 @@ Launchpad: the *ubuntu side* and the *upstream side.*
 Where possible, the two sides are unified (in technical terms) and
 integrated (in collaboration terms). But you'll see a lot of cases where
 they are treated somewhat differently. Permissions can differ,
-organizational structures differ, and some processes only exist on one
+organisational structures differ, and some processes only exist on one
 side or the other.
 
 At the most fundamental level, the two sides are integrated through:
@@ -153,7 +153,7 @@ or select a different translation message.
 
 A translation message can be *current* in a given PO file, or not. It's
 an emergent property of more complex shared data structures. So you can
-view a PO file as a customizable “view” on the current translations of a
+view a PO file as a customisable “view” on the current translations of a
 particular template into a given language.
 
 ::
@@ -301,7 +301,7 @@ Soyuz uploads are different in that regard: all its custom logic is
 built into the gardener because the two developed hand in hand. Mainly
 for this reason, the gardener's approval logic is fiendishly complex.
 
-Permissions and organization
+Permissions and organisation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Message sharing
@@ -332,7 +332,7 @@ In a nutshell:
 -  A \`POTranslation\` holds the text of a translated string;
    \`TranslationMessage\` refers to it (once for every plural form in
    the language).
--  A \`TranslationGroup\` is an organizational structure for managing
+-  A \`TranslationGroup\` is an organisational structure for managing
    translations.
 -  A \`Translator\` is an entry in a \`TranslationGroup\` saying who is
    responsible for a particular \`Language`.
@@ -352,7 +352,7 @@ multiple templates. We then call these templates *sharing templates.*
 And that means that a translation message to, say, Italian will be
 available in each of those templates' PO file for Italian.
 
-This is where it gets complicated; please fasten your seatbelts and
+This is where it gets complicated; please fasten your seat belts and
 extinguish smoking motherboards.
 
 A translation message can be in one of three sharing states:
@@ -394,7 +394,7 @@ current translation message? Look for one with:
 -  diverged to your template or, if no message matches, not diverged at
    all.
 
-(On a sidenote, this is why “simple” translation statistics can be quite
+(On a side note, this is why “simple” translation statistics can be quite
 hard to compute.)
 
 Which templates share?
@@ -518,7 +518,7 @@ translation page. Its complexity also makes the SQL logs hard to follow.
 A large part of this query (in terms of SQL text) was involved in
 finding out what templates were eligible for taking suggestions from.
 This part was also completely repetitive, and it doesn't even need to be
-immediately consistent, so we materialized it as a simple cache table
+immediately consistent, so we materialised it as a simple cache table
 called \`SuggestivePOTemplate`.
 
 We refresh this cache all the time by clearing out the table and

explanation/feature-flags.rst

@@ -3,7 +3,7 @@ Feature Flags
 
 .. include:: ../includes/important_not_revised.rst
 
-**FeatureFlags allow Launchpad's configuration to be changed while it's
+**Feature Flags allow Launchpad's configuration to be changed while it's
 running, and for particular features or behaviours to be exposed to only
 a subset of users or requests.**
 
@@ -23,15 +23,15 @@ Scenarios
 
 -  Dark launches (aka embargoes: land code first, turn it on later)
 -  Closed betas
--  Scram switches (eg "omg daily builds are killing us, make it stop")
+-  Scram switches (e.g. "omg daily builds are killing us, make it stop")
 -  Soft/slow launch (let just a few users use it and see what happens)
 -  Site-wide notification
 -  Show an 'alpha', 'beta' or 'new!' badge next to a UI control, then
    later turn it off without a new rollout
--  Show developer-oriented UI only to developers (eg the query count)
+-  Show developer-oriented UI only to developers (e.g. the query count)
 -  Control page timeouts (or other resource limits) either per page id,
    or per user group
--  Set resource limits (eg address space cap) for jobs.
+-  Set resource limits (e.g. address space cap) for jobs.
 
 Concepts
 --------
@@ -40,7 +40,7 @@ A **feature flag** has a string name, and has a dynamically-determined
 value within a particular context such as a web or api request. The
 value in that context depends on determining which **scopes** are
 relevant to the context, and what **rules** exist for that flag and
-scopes. The rules are totally ordered and the highest-prority rule
+scopes. The rules are totally ordered and the highest-priority rule
 determines the relevant value.
 
 Flags values are strings; or if no value is specified, \`None`. (If an
@@ -128,7 +128,7 @@ Flags should be named as
 where each of the parts is a legal Python name (so use underscores to
 join words, not dashes.)
 
-The **area** is the general area of Launchpad this relates to: eg
+The **area** is the general area of Launchpad this relates to: e.g.
 'code', 'librarian', ...
 
 The **feature** is the particular thing that's being controlled, such as
@@ -218,7 +218,7 @@ Adding and documenting a new feature flag
 -----------------------------------------
 
 If you introduce a new feature flag, as well as reading it from
-whereever is useful, you should also:
+wherever is useful, you should also:
 
 -  Add a section in lib/lp/services/features/flags.py flag_info
    describing the flag, including documentation that will make sense to
@@ -236,7 +236,7 @@ whereever is useful, you should also:
         ''),
 
 The last item in that list is descriptive, not prescriptive: it
-*documents the code's default behavior* if no value is specified. The
+*documents the code's default behaviour* if no value is specified. The
 flag's value will still read as None if no value is specified, and
 setting it to an empty value still returns the empty string.
 
@@ -267,7 +267,7 @@ and/or
 
    SCRIPT_SCOPE_HANDLERS
 
-depending on whether it applies to webapp requests, scripts, or both).
+depending on whether it applies to web app requests, scripts, or both).
 
 Testing
 -------

explanation/javascript-buildsystem.rst

@@ -34,8 +34,7 @@ Adding a third-party widget
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The current story for adding a third-party widget is to put it in
-``lib/lp/contrib``. You can read the mailing list discussion ( 
-https://lists.launchpad.net/launchpad-dev/msg06474.html ) about the adoption of
+``lib/lp/contrib``. You can read the `mailing list discussion`_ about the adoption of
 this location.
 
 For CSS, follow the rules above to modify the tools. If other assets are
@@ -44,6 +43,8 @@ needed, you'll need to create a link in
 ``lib/lp/contrib`` so the assets can be found. See
 ``lib/canonical/launchpad/icing/yui3-gallery`` for an example.
 
+.. _`mailing list discussion`: https://lists.launchpad.net/launchpad-dev/msg06474.html
+
 New Combo loader Setup
 ----------------------
 
@@ -54,7 +55,7 @@ minified into a build directory ``build/js/``.
 Files are served out of the ``build/js`` directory based on the YUI
 combo loader config that is constructed in the
 ``lib/lp/app/templates/base-layout-macros.pt``. These are combined and
-served out via the convoy wsgi application through Apache.
+served out via the convoy WSGI application through Apache.
 
 Developing Javascript
 ~~~~~~~~~~~~~~~~~~~~~
@@ -85,7 +86,7 @@ include that module name in any YUI block.
    LPJS.use('modulename', function (Y)...
 
 The combo loader will serve your new module when you reload the page
-ith that content on it.
+with that content on it.
 
 Launchpad CSS
 -------------

explanation/javascript-integration-testing.rst

@@ -1,18 +1,18 @@
 Integration Testing in JavaScript
 =================================
 
-Launchpad's JavaScript testing is built around YUI 3's yuitest library.
-We use the GradedBrowserSupport chart to determine which browsers code should
+Launchpad's JavaScript testing is built around YUI 3's ``yuitest`` library.
+We use the Graded Browser Support chart to determine which browser's code should
 be regularly tested in.
 
 Every JavaScript component should be tested first and foremost using
 :doc:`unit testing <javascript-unittesting>`.
 
-We have infrastructure to write tests centered on the integration
+We have infrastructure to write tests centred on the integration
 between the JavaScript component and the app server (regular API or
 view/++model++ page api.)
 
-These are still written using the \`yuitest\` library, but they are
+These are still written using the ``yuitest`` library, but they are
 loaded and can access a "real" appserver (the one started by the
 AppServerLayer).
 
@@ -32,7 +32,7 @@ Creating the tests
 -  The ``.js`` file contains the tests using the standard ``yuitest`` library.
 -  The ``.py`` file contains fixtures that will operate within the app server.
    They should create content through the standard LaunchpadObjectFactory that
-   will be accessed by the test through. The database is automatically reset
+   will be accessed by the test. The database is automatically reset
    after every test.
 
 Running the tests