This is an automated email from the ASF dual-hosted git repository.
klesh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/devlake-website.git
The following commit(s) were added to refs/heads/main by this push:
new 360b51c9b35 docs: document the DORA source branch pattern for lead
time for changes (#836)
360b51c9b35 is described below
commit 360b51c9b35dbd73d729ab267194affec055034b
Author: AwEi <[email protected]>
AuthorDate: Thu Oct 22 09:27:34 2026 +0800
docs: document the DORA source branch pattern for lead time for changes
(#836)
Companion to apache/devlake#9229, which adds a DORA project setting that
counts only merged pull requests whose source branch matches a regex.
Adds a "Choose which pull requests count" section to the Lead Time for
Changes page: why to use it, where to set it, how the pattern is matched,
examples, which metrics it affects, and the equivalent dora metric plugin
option. Links to it from the DORA page and the PR Cycle Time page.
---
docs/DORA.md | 10 +++++++++
docs/Metrics/LeadTimeForChanges.md | 43 ++++++++++++++++++++++++++++++++++++++
docs/Metrics/PRCycleTime.md | 2 ++
3 files changed, 55 insertions(+)
diff --git a/docs/DORA.md b/docs/DORA.md
index 49308324bb8..fb4c262b540 100644
--- a/docs/DORA.md
+++ b/docs/DORA.md
@@ -217,6 +217,16 @@ computes per-sub-project Deployment Frequency and Lead
Time for Changes.
<br/>
+## Count only some pull requests
+
+By default, every merged pull request counts toward Lead Time for Changes. If
your team
+merges changes through an intermediate branch, such as `release-uat`, the same
change can
+be counted twice. Set a source branch pattern on the project to count only the
pull
+requests from matching branches. See
+[Choose which pull requests
count](Metrics/LeadTimeForChanges.md#choose-which-pull-requests-count-optional).
+
+<br/>
+
## Try it Out
To create the DORA dashboard with your own toolchain, please look at the
[configuration tutorial](Configuration/Tutorial.md) and [project organization
documentation](Configuration/HowToOrganizeDevlakeProjects.md) for more details.
diff --git a/docs/Metrics/LeadTimeForChanges.md
b/docs/Metrics/LeadTimeForChanges.md
index dcbf0f47f1e..18f339cb19e 100644
--- a/docs/Metrics/LeadTimeForChanges.md
+++ b/docs/Metrics/LeadTimeForChanges.md
@@ -24,6 +24,8 @@ This metric is quite similar to [PR Cycle
Time](PRCycleTime.md). The difference
2. Find the associated pull requests of the commits diff between two
consecutive successful `deployment commits` in the production environment.
3. Calculate the PRs' median cycle time. This will be the Median Lead Time for
Changes.
+By default, every merged PR counts. To count only PRs from certain source
branches, see [Choose which pull requests
count](#choose-which-pull-requests-count-optional).
+
[PR cycle time](../Metrics/PRCycleTime.md) is pre-calculated by the `dora`
plugin during every data collection. You can find it in `pr_cycle_time` in
[table.project_pr_metrics](https://devlake.apache.org/docs/DataModels/DevLakeDomainLayerSchema/#project_pr_metrics)
of DevLake's database.
@@ -170,6 +172,47 @@ SELECT
FROM _median_change_lead_time
```
+## Choose which pull requests count (optional)
+
+Some teams merge changes into an intermediate branch first, then merge that
branch into production with one more PR, for example `feat/a` → `release-uat` →
`production`. By default, both PRs count, so the same change is measured twice.
Set a **source branch pattern** to count only the PRs that carry the actual
change.
+
+To set it:
+
+1. Open **Projects** → your project → **Settings**.
+2. Tick **Enable DORA Metrics** and enter a regular expression in the input
below it.
+3. Click **Save**, then re-run the project's blueprint. Re-transforming the
data is enough; you don't need to collect it again.
+
+| Item | Behavior
|
+|:------------------------|:-------------------------------------------------------------------------------------------------------------------------------|
+| Matched against | The PR's source branch (`pull_requests.head_ref`),
e.g. GitHub `head.ref` or GitLab `source_branch` |
+| Syntax | [Go regular
expression](https://pkg.go.dev/regexp/syntax) (RE2). Lookahead such as
`(?!...)` is not supported |
+| Anchors | Not added for you. `feat/` also matches
`my-feat/x`; use `^feat/` to match from the start
|
+| Case | Case-sensitive. Add `(?i)` to ignore case
|
+| `refs/heads/` prefix | Removed before matching (Azure DevOps)
|
+| Empty | Every merged PR counts (default)
|
+| Invalid expression | The blueprint fails to start and reports `invalid
prHeadRefPattern` |
+
+Examples:
+
+- `^(feat|fix)/`: only `feat/...` and `fix/...` branches.
+- `(?i)^(feat|fix|hotfix)/`: the same plus `hotfix/...`, ignoring case.
+
+PRs whose source branch does not match get no row in
[table.project_pr_metrics](https://devlake.apache.org/docs/DataModels/DevLakeDomainLayerSchema/#project_pr_metrics).
They are left out of Lead Time for Changes and of the PR time metrics that
read this table: [PR Cycle Time](./PRCycleTime.md), [PR Coding
Time](./PRCodingTime.md), [PR Pickup Time](./PRPickupTime.md), [PR Review
Time](./PRReviewTime.md) and [PR Deploy Time](./PRDeployTime.md). The PRs
themselves stay in `pull_requests`, [...]
+
+The same option can be set through the API or the Config UI's [advanced
mode](../Configuration/AdvancedMode.md) as the project's `dora` metric plugin
option:
+
+```json
+{
+ "pluginName": "dora",
+ "enable": true,
+ "pluginOption": {
+ "prHeadRefPattern": "^(feat|fix)/"
+ }
+}
+```
+
+The source branch pattern is available after the `v1.0.3-beta18` release.
+
## How to improve?
- Break requirements into smaller, more manageable deliverables
diff --git a/docs/Metrics/PRCycleTime.md b/docs/Metrics/PRCycleTime.md
index f2e00ccc49d..2c988bc5a2b 100644
--- a/docs/Metrics/PRCycleTime.md
+++ b/docs/Metrics/PRCycleTime.md
@@ -21,6 +21,8 @@ PR Cycle Time indicates the overall velocity of the delivery
progress in terms o
## How is it calculated?
You can define `deployment` based on your actual practice. For a full list of
`deployment`'s definitions that DevLake support, please refer to [Deployment
Frequency](/docs/Metrics/DeploymentFrequency.md).
+If the project sets a DORA source branch pattern, only PRs whose source branch
matches it are measured. See [Choose which pull requests
count](./LeadTimeForChanges.md#choose-which-pull-requests-count-optional).
+
<b>Data Sources Required</b>
This metric relies on PRs/MRs collected from GitHub, GitLab, BitBucket, Gitee
or other code review tools.
