Merge branch 'main' into ODA78-Launchpad_fix_broken_links-codehosting

.custom_wordlist.txt

@@ -1,5 +1,6 @@
 activereviews
 adapter
+adapters
 adapter's
 AddingLaunchpadCelebrity
 analyze
@@ -40,6 +41,7 @@ Bionic's
 Blazingly
 bool
 boolean
+BranchMergeProposal
 breakpoint
 browserconfig
 BrowserNotificationMessages
@@ -104,6 +106,7 @@ DateTimeJSONEncoder
 DatetimeUsageGuide
 DavidAllouche
 DBEnums
+DistributionSourcePackage
 dbpatches
 dbschema
 dbupgrade
@@ -328,6 +331,7 @@ os
 OSA
 OWASP
 OWASP's
+PackageBranchTarget
 PageSpeed
 pagespeed
 pagetest
@@ -336,6 +340,7 @@ pagetests
 pamola
 PatchSubmission
 pdb
+PersonBranchTarget
 pentested
 performant
 pgbouncer
@@ -386,6 +391,7 @@ pre_iter_hook
 prioritize
 prober
 proc
+ProductBranchTarget
 ProductSeries
 programmatically
 prometheus

.wordlist.txt

@@ -76,11 +76,14 @@ TODO
 Triaging
 tzinfo
 UI
+URL
 undercommunication
 updateable
 VM
+xsl
 xUnit
 XXXes
 YAML
 YUI
+wadl
 zpt

custom_conf.py

@@ -132,19 +132,16 @@
     'Debugging#Profiling%20page%20requests',  # needs update
     'Debugging#Special%20URLs',  # needs update
     'JavascriptUnitTesting/MockIo',  # needs update
-    'PolicyAndProcess/Accessibility',  # needs update
-    'Translations/Specs/UpstreamImportIntoUbuntu/FixingIsImported/setCurrentTranslation',  # 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
     'https://wiki.canonical.com/Launchpad/PolicyandProcess/ProductionChangeApprovalPolicy',  # private
     'https://deployable.ols.canonical.com/project/launchpad-db',  # private
     'irc.libera.chat',  # this is not an HTTP link
-    'attachment:TranslationsSchema.dia',  # needs update
     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
+    'https://git.zx2c4.com/cgit/', # unfortunately very flaky
     ]
 
 # Pages on which to ignore anchors

explanation/best-practices-for-development.rst

@@ -0,0 +1,12 @@
+Best practices for development
+==============================
+
+.. toctree::
+   :maxdepth: 1
+
+   architecture
+   charms
+   codeimport
+   performance
+   template-reuse
+   security-policy

explanation/code.rst

@@ -28,7 +28,7 @@ system. The major sub-systems are:
 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>`__
+The `codehosting overview diagram :attachment:../images/codehosting.png`
 summarises how some of these systems interact.
 
 You can :doc:`run the codehosting system locally <how-to/codehosting-locally>`.
@@ -135,9 +135,7 @@ kicked off.
 The web application
 -------------------
 
-Code that is executed as part of the Launchpad web application. The core
-`concepts </Concepts>`__ are documented on the
-`Code/Concepts </Concepts>`__ page.
+Code that is executed as part of the Launchpad web application. The core concepts are documented on the :doc:`Code Concepts <./concepts>` page.
 
 **Major features**
 

explanation/concepts.rst

@@ -0,0 +1,149 @@
+=============
+Code Concepts
+=============
+
+In order to fully understand the **\`lp.code\`** modules, it helps to
+have an understanding of a number of core concepts.
+
+Registry objects are those Launchpad-wide objects that are shared
+between the different Launchpad applications. The registry objects that
+**\`lp.code\`** modules are associated with are:
+
+-  Person
+-  Product
+-  Project
+-  !SourcePackage
+-  Distribution
+-  !DistroSeries
+-  !DistributionSourcePackage
+
+``  ''Please be aware of the confusion between ``\ *:literal:`\`Products\``*\ `` and ``\ *:literal:`\`Projects\``*\ `` in the codebase.  To the outside world a ``\ *:literal:`\`Product\``*\ `` is a project, and a ``\ *:literal:`\`Project\``*\ `` is a project group (or super-project).''``
+
+There are a few major concepts in **\`lp.code\`** to do with branches:
+
+-  `Branch <#branch>`__
+-  `Merge proposal <#merge-proposal>`__
+-  `Namespace <#namespace>`__
+-  `Target <#target>`__
+-  `Collection <#collection>`__
+
+<<Anchor(branch)>>
+
+Branch
+------
+
+The branch object in Launchpad refers to a real Bazaar branch.
+
+A branch has an owner. The owner can be either an individual or a team.
+The owner defines who can write to the branch.
+
+A branch also has a target. There are three current targets:
+
+-  !PersonBranchTarget - these are \`+junk\` branches
+-  !ProductBranchTarget - these are branches associated with a product,
+   sometimes called an upstream
+-  !PackageBranchTarget - these branches are associated with source
+   packages. A source package is effectively tuple of a particular
+   package name in a distribution series.
+
+You almost never need to know about these objects though, since they are
+!IBranchTarget adapters: \`IBranchTarget(person)`,
+\`IBranchTarget(product)`, \`IBranchTarget(source_package)`.
+
+A branch also has a name.
+
+Together the owner, target and name make the \`unique_name\` of the
+branch.
+
+<<Anchor(merge-proposal)>>
+
+Merge proposal
+--------------
+
+A merge proposal (`BranchMergeProposal`) is used to record information
+around the process of merging one branch into another.
+
+In situations where feature branches are used, it is normal for each
+feature branch to have a merge proposal for the main trunk branch. In
+these cases the feature branch is the \`source_branch`, and the trunk is
+the \`target_branch`.
+
+The code review process happens around a merge proposal. People can
+review and comment on the proposal, and proposals can be approved (or
+rejected) to land on the target branch.
+
+<<Anchor(namespace)>>
+
+Namespace
+---------
+
+A namespace is (usually?) an owner and a target.
+
+A namespace has exactly one branch collection associated with it. In
+some sense, it **is** a branch collection. (is-a could mean inheritance
+or adaptation).
+
+A namespace is, conceptually, everything up to the last part of a
+branch's unique name.
+
+There's no hierarchy of branches beneath a namespace.
+
+A branch belongs to exactly one namespace.
+
+::
+
+   IBranchNamespace
+     target :: IBranchTarget
+     getBranches() :: [IBranch]
+     createBranch(*args) :: IBranch
+
+<<Anchor(target)>>
+
+Target
+------
+
+**Target** is the most nebulous of these concepts. A target is a thing a
+branch is a branch \*of*, or perhaps a thing a branch lives on. A
+product is a target, a source package is a target, a person's +junk area
+is a target. A project (i.e. a collection of products) is not a target.
+
+Each branch has exactly one target.
+
+A target is not a namespace (in general). A +junk target is, at some
+level, a namespace, but other targets are not (only because +junk is
+associated with a person).
+
+A target has a collection naturally associated with it: the collection
+of all branches with that target. Does this mean a target is, in some
+sense, a collection? Probably not.
+
+::
+
+   IBranchTarget
+     context :: (registry object)
+     collection :: IBranchCollection
+     default_stacked_on_branch :: IBranch
+     default_merge_target :: IBranch
+     getNamespace(person) :: IBranchNamespace
+     -- implemented by BranchTarget only.
+
+<<Anchor(collection)>>
+
+Collection
+----------
+
+A collection has no semantic value beyond being a collection. It need
+not be tied to a specific registry object, namespace or target. "All
+branches" is a special, well-known branch collection. A collection is
+simply a clear API for "a bunch of branches". A collection is the
+preferred way of talking about a bunch of branches in our code-base.
+
+::
+
+   IBranchCollection
+     getBranches
+     getMergeProposals
+      - implemented using getBranches,
+      - merge proposals where the source branch is in getBranches()
+     # separately,
+     # a bunch of filter methods.

explanation/database.rst

@@ -0,0 +1,11 @@
+Database
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   postgresql
+   working-with-db-devel
+   live-patching
+   storm-migration-guide
+   database-performance

explanation/developing-the-launchpad-project.rst

@@ -0,0 +1,13 @@
+Developing the Launchpad project
+================================
+
+.. toctree::
+   :maxdepth: 1
+
+   branches
+   pre-merge-reviews
+   error-explanations
+   hacking
+   feature-flags
+   datetime-usage
+   xxx-policy

explanation/engineering-overview-translations.rst

@@ -315,9 +315,6 @@ Message sharing
 Objects and schema
 ------------------
 
-See my horrible `schema overview <attachment:TranslationsSchema.dia>`__
-(dia format).
-
 In a nutshell:
 
 -  A \`POTemplate\` lives in either a \`ProductSeries\` or a
@@ -370,9 +367,7 @@ A translation message can be in one of three sharing states:
 3. **Tracking.** The translation is not only shared on one translation
    side, but between both translation sides.
 
-We have a `design
-document <Translations/Specs/UpstreamImportIntoUbuntu/FixingIsImported/setCurrentTranslation>`__
-that specifies how messages in these states respond to changes. We try
+We have a design document that specifies how messages in these states respond to changes. We try
 to make it easy to move a translation down this list (towards tracking)
 and hard to move up the list (towards diverged).
 

explanation/ideas-behind-launchpad.rst

@@ -0,0 +1,10 @@
+The ideas behind Launchpad
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   scope
+   strategy
+   values
+   security