doc: high-performance builders

doc/user_documentation.rst

@@ -631,6 +631,13 @@ though they are recommended to do so. In particular, kernel modules
 may be built in Copr, as long as they don't violate the license
 requirements in point 2. above.
 
+.. _`Can you lend me powerful/faster Copr builders?`:
+
+.. rubric:: Can you lend me powerful/faster Copr builders? :ref:`¶ <Can you lend me powerful/faster Copr builders?>`
+
+Yes, but you don't always want this, see — :ref:`powerful_builders`.`
+
+
 .. _`Is it safe to use Copr?`:
 
 .. rubric::  Is it safe to use Copr? :ref:`¶ <Is it safe to use Copr?>`
@@ -776,6 +783,7 @@ Community projects (formerly Cool Other Package Repositories)
 .. rubric:: How can I tell yum to prefer Copr packages? :ref:`¶ <How can I tell yum to prefer Copr packages?>`
 
 Building a package with the same version-release number in Copr as the package distributed in the official Fedora repos is discouraged. You should instead bump the release number. Should you build with the same version-release number, you can tell yum to prefer the Copr packages over the distribution provided packages by adding cost=900 to the .repo file.
+TODO: ^^m priority
 
 .. _`Can Copr build directly from git?`:
 

doc/user_documentation/powerful_builders.rst

@@ -0,0 +1,48 @@
+:orphan:
+
+.. _powerful_builders:
+
+Default builders in Copr are too slow!
+======================================
+
+The default Fedora Copr workers are typically fast enough for the vast majority
+of package builds.  However, some package builds are extremely
+resource-intensive, and our default workers struggle with them.  A notable
+example is Blink_-based browsers, which can take even more than 24 hours to
+build.
+
+From a build system perspective, this isn't a problem.  You can simply specify
+``--timeout 180000`` (in seconds) and be prepared to wait for the build to
+finish.  But if you want to expedite your builds, you do have the option to
+request "powerful" builders.
+
+Pros & Cons
+-----------
+
+The "powerful" builders will handle your builds much faster (according to the
+configuration as of October 2023, they are approximately 8 times faster than the
+default builders).  The downside is that they are in limited supply.  We can
+only start a few of them, and if multiple users request them and compete with
+each other, they may spend more time in the queue, resulting in longer wait
+times.  Additionally, because these machines are costly, we don't pre-allocate
+them (as we do with the normal builders).  We only start these powerful ones
+when "enabled builds" request them (which may itself take several minutes).
+
+As a consequence, when you configure your project, chroot or package to use
+powerful builders, there's no "magical fallback to normal builders" implemented.
+You'll simply have to wait for the powerful builder.
+
+The rule of thumb is to avoid using high-performance workers for builds that are
+expected to complete in less than two hours on normal builders.
+
+How to request powerful builders
+--------------------------------
+
+As of October 2023, we only support powerful builders for ``x86`` and
+``aarch64`` architectures.  Please think carefully (ensure you understand the
+previous section, especially the cons) and submit an issue_.  Specify your
+project, chroot, and the packages you want to configure to use powerful
+builders.
+
+.. _Blink: https://en.wikipedia.org/wiki/Blink_(browser_engine)
+.. _issue: https://github.com/fedora-copr/copr/issues