[llvm] [CI] Update Best Practices on Job Events for Stacked PRs (PR #149734)

[Aiden Grossman via llvm-commits]

https://github.com/boomanaiden154 created https://github.com/llvm/llvm-project/pull/149734

I have seen a couple recent issues around workflows getting triggered on events that are not correctly configured to handle stacked PRs. This potentially resulted in workflows getting run twice (if they were also triggering on push events) or to not run at all (if there were branch restrictions for the pull_request event). Add some documentation to the best practices page so we can hopefully avoid these issues in the future and have some documentation to refer to during code review.

>From 00935f91969afbde2860112dd553a08b6b583908 Mon Sep 17 00:00:00 2001
From: Aiden Grossman <aidengrossman at google.com>
Date: Sun, 20 Jul 2025 19:44:54 +0000
Subject: [PATCH] [CI] Update Best Practices on Job Events for Stacked PRs

I have seen a couple recent issues around workflows getting triggered on
events that are not correctly configured to handle stacked PRs. This
potentially resulted in workflows getting run twice (if they were also
triggering on push events) or to not run at all (if there were branch
restrictions for the pull_request event). Add some documentation to the
best practices page so we can hopefully avoid these issues in the future
and have some documentation to refer to during code review.
---
 llvm/docs/CIBestPractices.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/llvm/docs/CIBestPractices.rst b/llvm/docs/CIBestPractices.rst
index 71fdd12d7cc6d..8301b95f54938 100644
--- a/llvm/docs/CIBestPractices.rst
+++ b/llvm/docs/CIBestPractices.rst
@@ -108,3 +108,31 @@ If specific jobs within the workflow need additional permissions, those
 permissions should be added within the specific job. This practice locks down
 all permissions by default and only enables them when needed, better enforcing
 the principle of least privilege.
+
+Ensuring Workflows Run on the Correct Events
+--------------------------------------------
+
+Github allows workflows to run on a multitude of events and it is important to
+configure a workflow such that it triggers on the correct events. There are
+two main best practices around events that trigger workflows:
+
+1. Workflows that are designed to run on pull requests should not be
+restricted by target branch. Restricting the target branch unnecessarily
+will prevent any stacked PRs from being tested. ``pull_request`` events should
+not contain a branches key.
+
+2. Workflows that are designed to also trigger on push events (e.g., for
+testing on ``main`` or one of the release branches) need to be restricted by
+branch. While pushes to a fork will not trigger a workflow run due to the
+``push`` event if the workflow already has its jobs disabled in forks
+(described above), stacked PRs will end up running jobs twice if the ``push``
+event does not have any branch restrictions. ``push`` events should have
+their branches restricted at the very least to ``main`` and the release
+branches as follows:
+
+.. code-block:: yaml
+
+  push:
+    branches:
+      - main
+      - releases/*