doc: high-performance builders

Closes: fedora-copr#2971
Relates: fedora-copr#2241

Author: praiskup

doc/user_documentation.rst

@@ -631,6 +631,12 @@ 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 faster Copr builders? :ref:`¶ <Can you lend me powerful/faster Copr builders?>`
+
+Yes, glad you asking!  But you don't always want this, see — :ref:`high_performance_builders`.
+
 .. _`Is it safe to use Copr?`:
 
 .. rubric::  Is it safe to use Copr? :ref:`¶ <Is it safe to use Copr?>`

doc/user_documentation/powerful_builders.rst

@@ -0,0 +1,53 @@
+:orphan:
+
+.. _high_performance_builders:
+
+Builders in Fedora Copr are too slow!
+=====================================
+
+The *normal* Fedora Copr builders are typically fast enough for the vast majority
+of package builds.  However, some package builds are extremely
+resource-intensive, and our *normal builders* 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 *high-performance builders*.
+
+Pros & Cons of *high-performance builders*
+------------------------------------------
+
+Once you get them, the *high-performance builders* will handle your builds much
+faster.  According to the specification as of October 2023, they are
+approximately 8 times faster than the *normal builders*, but the actual speedup
+is very task-dependent.
+
+The downside is that they are in limited supply. If other users request them at
+the same time as you, you'll compete with others, and you may spend a bit longer
+waiting in the queue until one such machine is allocated for you (*starting*
+phase of the build).
+
+Also, because these machines are costly, we never pre-allocate them (as we do
+with the normal builders to generally minimize the initial waiting).  We only
+start these *high-performance* ones when a specific build request them.  Waiting
+for the corresponding machine to start may take several additional minutes.
+
+It's worth noting that when you configure your project, chroot, or package to
+use *high-performance builders*, you will get them, sooner or later.  There's no
+magical "fallback to normal builders".  **The rule of thumb** is to avoid using
+*high-performance builders* for builds that are expected to complete in less than
+two hours on *normal builders*.
+
+How to request *high-performance builders*
+------------------------------------------
+
+As of October 2023, we only support *high-performance builders* for ``x86`` and
+``aarch64`` architectures.  Please think carefully (ensure you understand the
+previous section) and submit an issue_.  The pattern we have to configure for you
+is basically a Python regexp in a format ``owner/project/chroot/package``, e.g.
+``@asahi/kernel/.(x86_64|aarch64)/kernel.*``.
+
+.. _Blink: https://en.wikipedia.org/wiki/Blink_(browser_engine)
+.. _issue: https://github.com/fedora-copr/copr/issues