duel 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 15e688ef3d4a4d3c89f10bfef8621961c6025933456c845c3cdca1d048b3d2dd
4
- data.tar.gz: 71d90787a6a0993a5161acd2f7e9594498bc2e6e297d07d3970acd86c07471c5
3
+ metadata.gz: 2528f9b36dd187ea88916fa507ab544b243a58b6c74cfe9c75083c127d9c3bbb
4
+ data.tar.gz: ca3838705ef0db2b367c115e96e555fb346173be3aa7a1a1f1740e7a5c895a40
5
5
  SHA512:
6
- metadata.gz: 3275eb44aeec1133c699604b391c716a989242e657acd51fb48fb2ebb8aabad55f658b09151e5c07250a07f4d9d1e5e7b201bbd47f6e760b4b30a9516a6681f7
7
- data.tar.gz: 795438481087f53a0cb8faee6a61155d787ef5d808c079f2a222e1f0b2a12d957526080103d7d144990f096f1482dcd60bc27c9321f252f619a005a0eb4d2a3a
6
+ metadata.gz: 0663ad25b83ffa57ff1fdedb64c462c8fea600967d26ec49831071bf69fa4ebfbbf2a9a17f8ed1bdfbb3c8bb7a55757cea1fd9a6ad3937bb435ed849dda4ab55
7
+ data.tar.gz: d2b0f54723cfe98dbffa56103b5699bc532b9d305c2d75f5304d2749de0f1c455ab12c6250afbf8932537b7a883a6101bf61f242a0e7c5f24f65f866d60e6fb5
data/AGENT_PROMPT.md CHANGED
@@ -17,10 +17,11 @@ at the API.
17
17
  development group (unless the Gemfile has it already), and run
18
18
  `bundle install`. Then, unless the project is a Rails app (see step
19
19
  4), run `bundle exec duel init`, and read what it wrote: `.duel.rb`,
20
- an example benchmark in `duel/`, the GitHub Actions workflow
21
- (`.github/workflows/perf.yml`), Duel's Rake task, if there's a
22
- Rakefile, and `gem "stackprof", platforms: :mri` in the Gemfile, for
23
- profiles of regressions. It lists what it did and what's next: run
20
+ an example benchmark in `duel/`, two GitHub Actions workflows
21
+ (`.github/workflows/perf.yml`, and `perf-comment.yml`, which comments
22
+ on pull requests), Duel's Rake task, if there's a Rakefile, and
23
+ `gem "stackprof", platforms: :mri` in the Gemfile, for profiles of
24
+ regressions. It lists what it did and what's next: run
24
25
  `bundle install` again for StackProf.
25
26
 
26
27
  2. **Find what's worth guarding.** Read the code and its tests to find
@@ -58,6 +59,22 @@ at the API.
58
59
  includes what differs between the two versions' workers, like a
59
60
  server's socket path or a worker's directory: don't time work on
60
61
  it.
62
+ - Build inputs without the code you're measuring. Each version's
63
+ workers run the benchmarks with that version's code, so an input
64
+ made with the project's own encoder (its `dump`, `to_json` or
65
+ `serialize`) differs wherever the two versions' output does, and
66
+ the benchmark then compares different work. Write the input out as
67
+ a fixture, or build it from literals or Ruby's standard library.
68
+ See "Give both versions the same work" in Duel's
69
+ `docs/benchmarks.md`.
70
+ - Leave process-wide settings alone. Every worker loads every
71
+ benchmark file, so a mode, patch or global option that changes the
72
+ whole process (an `optimize` call, a changed default) changes every
73
+ benchmark that runs after it, and the default path goes unmeasured.
74
+ Never turn one on in `duel_helper.rb` or at a file's top level.
75
+ Turn it on only in the benchmarks that are about it, and put it
76
+ back in `teardown`, or measure it in a process of its own with
77
+ `duel_process`.
61
78
  - Use the sizes the code really sees. Read it for limits and
62
79
  constants (a cap on how many items it ever handles, say) rather
63
80
  than guessing.
@@ -135,9 +152,12 @@ at the API.
135
152
  there. Run `duel init` there too: it puts the workflow at the
136
153
  repository's root, and runs it in the subdirectory.
137
154
 
138
- Make sure the linter checks `.duel.rb`. It's a dotfile, so RuboCop
139
- leaves it out unless its config includes it (`AllCops: Include`,
140
- merged with the defaults by `inherit_mode`).
155
+ Don't change the project's own configuration beyond what `duel init`
156
+ did: its linter's config, its README (but for step 7), its other CI
157
+ workflows. Those are the maintainers' choices. If the linter flags
158
+ the benchmarks, fix the benchmarks. If it can't be satisfied without
159
+ a config change (it leaves `.duel.rb` out, say, as RuboCop does with
160
+ dotfiles), say so in your report instead.
141
161
 
142
162
  5. **Check that the guards hold.** While you're still writing
143
163
  benchmarks, run a few at a time (`bundle exec duel --force --filter
@@ -171,29 +191,39 @@ at the API.
171
191
  your names can be picked out. Without `--force`, a tree with
172
192
  nothing changed since the main branch has nothing to compare.
173
193
 
174
- 6. **Check CI.** `duel init` wrote Duel's GitHub Actions
175
- workflow (`.github/workflows/perf.yml`). Keep `fetch-depth: 0`:
176
- Duel's baseline comes from git history. Keep its check for a push
177
- with no commit before it in the history (a branch's first push, or a
178
- force push), which would otherwise fail the job. Keep its Comment
179
- job, which comments on a pull request with Duel's report when a
180
- benchmark fails (Duel also adds the report to the job's summary, and
181
- `c.comment` in `.duel.rb` chooses when it comments), and keep
182
- `pull-requests: write` on that job alone: the Duel job runs the
183
- branch's code, so it only reads. Check that `ruby-version` is one the project supports, unless
184
- it has a `.ruby-version`. With `c.ruby = :version_file` and another
185
- version file than `.ruby-version`, add the steps in Duel's
186
- `docs/ci.md` that install the baseline's Ruby, reading that file
187
- instead. If `.duel.rb` sets `c.main_branch` or `c.release_tags`, set
188
- those steps' `MAIN_BRANCH` or `RELEASE_TAGS` to match. Add the
189
- project's other CI setup that its tests need (system packages,
190
- services) to the Duel job as well. Keep the scheduled `last-release`
191
- run only if the project tags its releases (`v*` by default, or else
192
- set `c.release_tags`), or leave the schedule out. Until the first release is tagged, that run says
193
- there's nothing to compare against, and passes. Once it's pushed,
194
- run the workflow by hand: it compares the code with itself there,
195
- which shows that the benchmarks run on CI's machines (with their
196
- packages and services).
194
+ 6. **Check CI.** `duel init` wrote two GitHub Actions workflows.
195
+ - `.github/workflows/perf.yml` runs Duel. Keep `fetch-depth: 0`:
196
+ Duel's baseline comes from git history. Keep its check for a push
197
+ with no commit before it in the history (a branch's first push, or
198
+ a force push), which would otherwise fail the job. The Duel job
199
+ runs the branch's code, so it only reads: don't give it, or the
200
+ workflow, any write permission.
201
+ - `.github/workflows/perf-comment.yml` comments on a pull request
202
+ with Duel's report once the first has run (`c.comment` in
203
+ `.duel.rb` chooses when, and Duel also adds the report to the
204
+ job's summary). It runs none of the pull request's code, and shows
205
+ a fork's report as text. Keep it as it is.
206
+ - `duel init` writes the jobs for pushes (a comment on a pushed
207
+ commit, and a `duel/passed/` branch that marks the last commit
208
+ Duel passed) only where `.duel.rb` sets `c.fail_on =
209
+ :pull_requests` or `c.push_base = :last_passed`, and the badge's
210
+ job only with `--badge`. Each needs `contents: write`, so don't
211
+ set those settings, or add those jobs, unless I ask.
212
+
213
+ Check that `ruby-version` is one the project supports, unless it has
214
+ a `.ruby-version`. With `c.ruby = :version_file` and another version
215
+ file than `.ruby-version`, add the steps in Duel's `docs/ci.md` that
216
+ install the baseline's Ruby, reading that file instead. If
217
+ `.duel.rb` sets `c.main_branch` or `c.release_tags`, set those
218
+ steps' `MAIN_BRANCH` or `RELEASE_TAGS` to match. Add the project's
219
+ other CI setup that its tests need (system packages, services) to
220
+ the Duel job as well. Keep the scheduled `last-release` run only if
221
+ the project tags its releases (`v*` by default, or else set
222
+ `c.release_tags`), or leave the schedule out. Until the first
223
+ release is tagged, that run says there's nothing to compare against,
224
+ and passes. Once it's pushed, run the workflow by hand: it compares
225
+ the code with itself there, which shows that the benchmarks run on
226
+ CI's machines (with their packages and services).
197
227
 
198
228
  7. **Show the badge.** If the project's README already shows badges (CI
199
229
  status, gem version), add Duel's to that row, with exactly this
@@ -203,7 +233,10 @@ at the API.
203
233
  [![Duel](https://raw.githubusercontent.com/sferik/duel-ruby/main/assets/badge.svg)](https://github.com/sferik/duel-ruby)
204
234
  ```
205
235
 
206
- If the README has no badges, don't add a row just for Duel's.
236
+ If the README has no badges, don't add a row just for Duel's. This
237
+ badge is always green: one that turns red when Duel fails a push
238
+ needs the badge's job (`duel init --badge`), so add that only if I
239
+ ask.
207
240
 
208
241
  8. **Report back** with:
209
242
  - The benchmarks you wrote and what each one guards.
@@ -211,5 +244,9 @@ at the API.
211
244
  - The output of the self-comparison and of the deliberate-regression
212
245
  check.
213
246
  - Anything you couldn't guard reliably.
247
+ - Every file you changed outside `duel/` and `.duel.rb`, and why.
248
+ - The label that lets a pull request that's slower on purpose pass
249
+ (`c.accept_label`, `duel: accept` in the `.duel.rb` that
250
+ `duel init` writes), which the repository needs to have.
214
251
 
215
252
  Don't commit. Leave the changes for me to review.
data/CHANGELOG.md CHANGED
@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.1.5] - 2026-11-08
11
+
12
+ ### Changed
13
+
14
+ - `duel init` writes the Comment on the commit job only where `.duel.rb`
15
+ sets `c.fail_on = :pull_requests`, and the Mark the commit passed job
16
+ only where it sets `c.push_base = :last_passed`, as with the defaults
17
+ neither runs, and each asks for `contents: write`. It reads the
18
+ settings from `.duel.rb` where there is one, and where that doesn't
19
+ load (one of its plugins isn't installed, say), writes both, and says
20
+ so. To add a job later, set its setting, remove the workflow, and run
21
+ `duel init` again, or add it from the guide.
22
+ - `duel init` writes the Update the badge job only with `--badge`. It
23
+ pushes a branch, so it needs `contents: write`, and without the jobs
24
+ for pushes, it was the workflow's only job that writes to the
25
+ repository. The workflow `duel init` writes by default now only reads.
26
+ To keep a badge you already show, add `--badge` when you run
27
+ `duel init` again, or keep the job you have.
28
+ - The `.duel.rb` that `duel init` writes sets
29
+ `c.accept_label = "duel: accept"`, so a pull request that's slower on
30
+ purpose can pass with that label. Duel's own default is still no
31
+ label, so a `.duel.rb` you already have is unchanged.
32
+ - `require "duel/rake_task"` loads only the task, and the task loads
33
+ Duel as it runs, so a Rakefile with Duel's task no longer loads all of
34
+ Duel (and what it requires) for every other task, `rake test` included.
35
+
36
+ ### Fixed
37
+
38
+ - The Perf comment workflow posted the report that a pull request's run
39
+ wrote as Markdown, as `github-actions[bot]`. A fork's run runs the
40
+ fork's code, which could write anything there, mentions, links and
41
+ images included. A fork's report is now shown as text, in a code
42
+ block, where it can't do any of that, and cut short where a comment
43
+ couldn't hold it. A pull request from a branch of the repository, whose
44
+ author can push to it anyway, still gets the Markdown. Update
45
+ `.github/workflows/perf-comment.yml` to pick this up.
46
+ - The Update the badge job downloaded the badge's image from Duel's own
47
+ repository, so a change there changed every project's badge, and a
48
+ failed download failed the job. It now writes the image itself, and
49
+ fetches nothing. Update it in `.github/workflows/perf.yml` to pick
50
+ this up.
51
+ - Two pushes' runs of the Update the badge job could overlap, as a
52
+ push's run doesn't wait for the one before it, and an older push's
53
+ could write its badge over a newer one's after both had checked
54
+ which push the badge was for. The job now runs one at a time. Update
55
+ it in `.github/workflows/perf.yml` to pick this up.
56
+
10
57
  ## [0.1.4] - 2026-11-06
11
58
 
12
59
  ### Fixed
@@ -527,7 +574,8 @@ needs Ruby 3.4 or later (or JRuby 10, or TruffleRuby 40).
527
574
  Anything marked `@api private`, in lib/ and sig/, may change in any
528
575
  release.
529
576
 
530
- [Unreleased]: https://github.com/sferik/duel-ruby/compare/v0.1.4...HEAD
577
+ [Unreleased]: https://github.com/sferik/duel-ruby/compare/v0.1.5...HEAD
578
+ [0.1.5]: https://github.com/sferik/duel-ruby/compare/v0.1.4...v0.1.5
531
579
  [0.1.4]: https://github.com/sferik/duel-ruby/compare/v0.1.3...v0.1.4
532
580
  [0.1.3]: https://github.com/sferik/duel-ruby/compare/v0.1.2...v0.1.3
533
581
  [0.1.2]: https://github.com/sferik/duel-ruby/compare/v0.1.1...v0.1.2
data/README.md CHANGED
@@ -83,7 +83,10 @@ out are Duel's.
83
83
 
84
84
  `duel init` doesn't overwrite a file that exists. To overwrite it, use
85
85
  `--force`. To see what `duel init` would do without writing anything,
86
- use `--dry-run`. When it's done, `duel init` lists the next steps.
86
+ use `--dry-run`. For a badge in your README that turns red when Duel
87
+ fails a push, use `--badge` (see
88
+ [Show that a project is guarded](#show-that-a-project-is-guarded)).
89
+ When it's done, `duel init` lists the next steps.
87
90
 
88
91
  For a Rails app, use
89
92
  [duel-rails](https://github.com/sferik/duel-ruby/tree/main/plugins/rails)
@@ -335,17 +338,17 @@ says.
335
338
  ### Show that a project is guarded
336
339
 
337
340
  To show that Duel guards your project, add its badge to your README,
338
- next to your other badges. With the workflow that `duel init` writes,
339
- the badge turns red when Duel fails a push to your default branch.
340
- Replace `OWNER/REPO` with your repository's:
341
+ next to your other badges. With the job that `duel init --badge` adds to
342
+ its workflow, the badge turns red when Duel fails a push to your default
343
+ branch. Replace `OWNER/REPO` with your repository's:
341
344
 
342
345
  ```markdown
343
346
  [![Duel](https://raw.githubusercontent.com/OWNER/REPO/duel/badge/badge.svg)](https://github.com/sferik/duel-ruby)
344
347
  ```
345
348
 
346
349
  See [Show whether the last push passed](docs/ci.md#show-whether-the-last-push-passed)
347
- for how the workflow keeps it. Without the workflow, such as on GitLab
348
- CI, use Duel's own badge, which is always green:
350
+ for how the job keeps it. Without the job, such as on GitLab CI, use
351
+ Duel's own badge, which is always green:
349
352
 
350
353
  ```markdown
351
354
  [![Duel](https://raw.githubusercontent.com/sferik/duel-ruby/main/assets/badge.svg)](https://github.com/sferik/duel-ruby)
@@ -388,8 +391,8 @@ plugin, see [Write a Duel plugin](docs/plugins.md).
388
391
  The [Duel guide](docs/README.md) covers the rest:
389
392
 
390
393
  - [Write benchmarks](docs/benchmarks.md): hooks, undoing each
391
- iteration, sharing code, choosing what a benchmark is judged on, and
392
- benchmarking a whole process.
394
+ iteration, sharing code, giving both versions the same work, choosing
395
+ what a benchmark is judged on, and benchmarking a whole process.
393
396
  - [Configure Duel](docs/configuration.md): `.duel.rb`, preparing each
394
397
  worker and each version, each version's own Ruby, your own metrics,
395
398
  and plugins.
data/docs/README.md CHANGED
@@ -5,7 +5,7 @@ benchmark, run it, and run it in CI. This guide covers the rest.
5
5
 
6
6
  | Page | What it covers |
7
7
  |---|---|
8
- | [Write benchmarks](benchmarks.md) | Hooks that run code around a benchmark, starting every sample alike, undoing each iteration, measuring work that a benchmark leaves for later, sharing code between benchmarks, choosing what a benchmark is judged on, and benchmarking a whole process. |
8
+ | [Write benchmarks](benchmarks.md) | Hooks that run code around a benchmark, starting every sample alike, undoing each iteration, measuring work that a benchmark leaves for later, sharing code between benchmarks, giving both versions the same work, choosing what a benchmark is judged on, and benchmarking a whole process. |
9
9
  | [Configure Duel](configuration.md) | `.duel.rb` and its settings, preparing each worker and each version, running code in each worker, running each version on its own Ruby, adding your own metrics, and using plugins. |
10
10
  | [Run Duel in CI](ci.md) | The GitHub Actions workflow that `duel init` writes, catching slow creep, commenting on a pull request, and installing the baseline's Ruby on CI. |
11
11
  | [How Duel works](how-it-works.md) | How Duel tells a regression from noise, what it measures, where the extra time went, where the baseline comes from, and JIT compilers, including JRuby and TruffleRuby. |
data/docs/benchmarks.md CHANGED
@@ -2,9 +2,9 @@
2
2
 
3
3
  This page covers what a benchmark can do beyond timing a block: run
4
4
  code around its samples and iterations, share code with other
5
- benchmarks, choose what it's judged on, and benchmark a whole process.
6
- For a first benchmark, with `once`, `untimed`, and a block that takes
7
- the number of iterations, see
5
+ benchmarks, give both versions the same work, choose what it's judged
6
+ on, and benchmark a whole process. For a first benchmark, with `once`,
7
+ `untimed`, and a block that takes the number of iterations, see
8
8
  [Write a benchmark](../README.md#write-a-benchmark).
9
9
 
10
10
  ## Run code around a benchmark
@@ -198,6 +198,35 @@ benchmarks: `duel`, `duel_process`, `once`, `untimed`, the hooks
198
198
  Duel's method would hide a helper of the same name, so the worker
199
199
  fails, and names the helper's file and line.
200
200
 
201
+ ## Give both versions the same work
202
+
203
+ Each version's workers load your benchmarks with that version's code,
204
+ so a benchmark compares like with like only where both versions are
205
+ given the same work.
206
+
207
+ Build a benchmark's inputs without the code it measures. A JSON
208
+ parser's benchmark that builds its document with the library's own
209
+ `dump` parses whatever each version dumps: where a change makes `dump`
210
+ write something else, the two versions parse different documents, and
211
+ the comparison measures that, not the parser. Write the input out, read
212
+ it from a file, or build it with code that both versions share, such as
213
+ Ruby's own.
214
+
215
+ ```ruby
216
+ # duel/parser_duel.rb
217
+ DOCUMENT = File.read(File.join(__dir__, "fixtures", "document.json"))
218
+
219
+ duel("parse: a document") { MyParser.parse(DOCUMENT) }
220
+ ```
221
+
222
+ Every worker loads every file of benchmarks, so a setting that changes
223
+ the whole process, such as a library's global option or a patch that a
224
+ mode installs, changes every benchmark that runs after it, in every
225
+ file. Turn it on in the benchmark's own hooks, and put it back in
226
+ `teardown`, or benchmark it in a process of its own, with
227
+ `duel_process`. Then the benchmarks that don't ask for it measure the
228
+ code that they name.
229
+
201
230
  ## Choose what a benchmark is judged on
202
231
 
203
232
  By default, Duel judges each benchmark on its timings and its counts:
data/docs/ci.md CHANGED
@@ -126,148 +126,6 @@ jobs:
126
126
  path: ${{ runner.temp }}/duel/
127
127
  if-no-files-found: ignore # none when Duel didn't get to compare
128
128
  retention-days: 1
129
-
130
- # The report, as a new comment on a pushed commit, which notifies its
131
- # author, when Duel says to, as for a pull request (see the Perf comment
132
- # workflow). It does only where a regression in a push passes, with
133
- # c.fail_on = :pull_requests in .duel.rb, so the comment says what the
134
- # check doesn't. Its last comment is the last one on any commit. This
135
- # job checks nothing out and runs none of the code.
136
- commit-comment:
137
- name: Comment on the commit
138
- needs: duel
139
- if: ${{ !cancelled() && github.event_name == 'push' && (needs.duel.outputs.comment == 'post' || needs.duel.outputs.comment == 'change') }}
140
- runs-on: ubuntu-latest
141
- permissions:
142
- contents: write # to comment on the commit with the report
143
- steps:
144
- - name: Get the report
145
- id: report
146
- continue-on-error: true # there's none when the Duel job failed before comparing
147
- uses: actions/download-artifact@v8
148
- with:
149
- name: duel-report
150
- path: ${{ runner.temp }}/report
151
- - name: Comment on the commit
152
- if: steps.report.outcome == 'success'
153
- env:
154
- GH_TOKEN: ${{ github.token }}
155
- COMMENT: ${{ needs.duel.outputs.comment }}
156
- STATUS: ${{ needs.duel.outputs.status }}
157
- run: |
158
- marker="<!-- duel"
159
- last=$(gh api --paginate "repos/$GITHUB_REPOSITORY/comments" \
160
- --jq ".[] | select(.user.login == \"github-actions[bot]\") | .body | split(\"\n\")[0] | rtrimstr(\"\r\") | select(startswith(\"$marker status=\"))" | tail -n 1)
161
- if [ "$COMMENT" = post ] || { [ -n "$last" ] && [ "$last" != "$marker status=$STATUS -->" ]; }; then
162
- { echo "$marker status=$STATUS -->"; cat "$RUNNER_TEMP/report/duel.md"; } > "$RUNNER_TEMP/comment.md"
163
- gh api --method POST "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
164
- fi
165
-
166
- # With c.push_base = :last_passed in .duel.rb, a push is compared with
167
- # the last commit Duel passed, which a branch marks (each branch pushed
168
- # has its own), so slowdowns too small for any one push to fail add up
169
- # until they fail one. This job moves the branch to a push that passed
170
- # (or makes it), but never back: where a newer push's run moved it
171
- # first, it stays. It checks nothing out and runs none of the code. To
172
- # accept a regression, move the branch yourself (for main, git push
173
- # origin main:duel/passed/main).
174
- passed:
175
- name: Mark the commit passed
176
- needs: duel
177
- if: ${{ !cancelled() && github.event_name == 'push' && needs.duel.outputs.passed == 'true' }}
178
- runs-on: ubuntu-latest
179
- permissions:
180
- contents: write # to move the branch
181
- steps:
182
- - name: Move the branch to the commit
183
- env:
184
- GH_TOKEN: ${{ github.token }}
185
- BRANCH: duel/passed/${{ github.ref_name }}
186
- run: |
187
- # (Git can't make a branch where another's name is a folder of its
188
- # name: a branch named duel blocks duel/passed/main. If one does,
189
- # this names it.)
190
- blocked() {
191
- prefix=$BRANCH
192
- while [ "${prefix%/*}" != "$prefix" ]; do
193
- prefix=${prefix%/*}
194
- if gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$prefix" > /dev/null 2>&1; then
195
- echo "::error::The branch $prefix keeps Duel from making $BRANCH, as Git can't have both. Delete it (git push origin --delete $prefix), or rename it."
196
- fi
197
- done
198
- exit 1
199
- }
200
- # (Forward: GitHub moves it only where it's behind the push.)
201
- gh api --method PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$GITHUB_SHA" > /dev/null 2>&1 && exit 0
202
- at=$(gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$BRANCH" --jq .object.sha 2>/dev/null) || at=
203
- if [ -z "$at" ]; then
204
- gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$GITHUB_SHA" > /dev/null || blocked
205
- exit 0
206
- fi
207
- compared=$(gh api "repos/$GITHUB_REPOSITORY/compare/$GITHUB_SHA...$at" --jq .status 2>&1) || case "$compared" in
208
- # (GitHub can't compare commits with no history in common.)
209
- *"No common ancestor"*) compared=unrelated ;;
210
- esac
211
- case "$compared" in
212
- # (A newer push's run moved it, or this one's did, run again.)
213
- ahead | identical) ;;
214
- # (History rewritten, a force push's, say, or replaced: moved anyway.)
215
- diverged | behind | unrelated) gh api --method PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$GITHUB_SHA" -F force=true > /dev/null ;;
216
- *) echo "::error::Couldn't compare $BRANCH with this push: $compared" && exit 1 ;;
217
- esac
218
-
219
- # Duel's badge, for the README: green (perf guarded) or red (perf
220
- # regressed), as the last push to the default branch that Duel compared
221
- # left it. It's red where the Duel job failed or found a regression,
222
- # even one that passed (with c.fail_on = :pull_requests in .duel.rb). A
223
- # push with nothing to compare leaves it as it was, and so does a run
224
- # for an older push than the badge's. This job writes the badge, alone,
225
- # to a branch of its own, which the README shows:
226
- #
227
- # [![Duel](https://raw.githubusercontent.com/OWNER/REPO/duel/badge/badge.svg)](https://github.com/sferik/duel-ruby)
228
- #
229
- # It checks nothing out and runs none of the code.
230
- badge:
231
- name: Update the badge
232
- needs: duel
233
- if: ${{ !cancelled() && github.event_name == 'push' && github.ref_name == github.event.repository.default_branch && (needs.duel.result == 'failure' || needs.duel.outputs.status == 'passed' || needs.duel.outputs.status == 'failed') }}
234
- runs-on: ubuntu-latest
235
- permissions:
236
- contents: write # to move the badge's branch
237
- steps:
238
- - name: Update the badge
239
- env:
240
- GH_TOKEN: ${{ github.token }}
241
- BRANCH: duel/badge
242
- RESULT: ${{ needs.duel.result }}
243
- STATUS: ${{ needs.duel.outputs.status }}
244
- BADGES: https://raw.githubusercontent.com/sferik/duel-ruby/main/assets
245
- run: |
246
- # (Git can't make a branch where another's name is a folder of its
247
- # name: a branch named duel blocks duel/passed/main. If one does,
248
- # this names it.)
249
- blocked() {
250
- prefix=$BRANCH
251
- while [ "${prefix%/*}" != "$prefix" ]; do
252
- prefix=${prefix%/*}
253
- if gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$prefix" > /dev/null 2>&1; then
254
- echo "::error::The branch $prefix keeps Duel from making $BRANCH, as Git can't have both. Delete it (git push origin --delete $prefix), or rename it."
255
- fi
256
- done
257
- exit 1
258
- }
259
- # (Where the badge is a newer push's, that push's run has the say.
260
- # Its commit names the push.)
261
- last=$(gh api "repos/$GITHUB_REPOSITORY/commits/$BRANCH" --jq .commit.message 2>/dev/null | sed -n 's/^Duel.s badge, for \([0-9a-f]*\)$/\1/p') || true
262
- if [ -n "$last" ] && [ "$(gh api "repos/$GITHUB_REPOSITORY/compare/$GITHUB_SHA...$last" --jq .status 2>/dev/null)" = ahead ]; then exit 0; fi
263
- badge="badge.svg"
264
- if [ "$RESULT" = failure ] || [ "$STATUS" = failed ]; then badge="badge-regressed.svg"; fi
265
- curl -fsSL "$BADGES/$badge" -o "$RUNNER_TEMP/badge.svg"
266
- tree=$(jq -n --rawfile svg "$RUNNER_TEMP/badge.svg" '{tree: [{path: "badge.svg", mode: "100644", type: "blob", content: $svg}]}' |
267
- gh api --method POST "repos/$GITHUB_REPOSITORY/git/trees" --input - --jq .sha)
268
- commit=$(gh api --method POST "repos/$GITHUB_REPOSITORY/git/commits" -f message="Duel's badge, for $GITHUB_SHA" -f tree="$tree" --jq .sha)
269
- gh api --method PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$commit" -F force=true > /dev/null 2>&1 ||
270
- gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$commit" > /dev/null || blocked
271
129
  ```
272
130
 
273
131
  A newer push to a pull request cancels the pull request's run, if it's
@@ -355,9 +213,12 @@ the pull request's code. The pull request's code ran in the Duel job,
355
213
  and could have written anything into the artifact, so the workflow
356
214
  trusts only what Duel could have said there: a number that names the
357
215
  pull request whose head the run compared, and a `comment` and a
358
- `status` that Duel uses. The report's Markdown is the comment's body,
359
- which can only say something on the pull request that the pull request
360
- could say itself. When the Duel job fails before it compares, there's
216
+ `status` that Duel uses. For a pull request from a branch of your
217
+ repository, whose author can push to it anyway, the report's Markdown
218
+ is the comment's body. For one from a fork, the report is shown as text,
219
+ in a code block, since the fork's code wrote it: there, posted by
220
+ `github-actions[bot]`, it can't mention anyone, link anywhere or show an
221
+ image. A report too long for a comment is cut short. When the Duel job fails before it compares, there's
361
222
  no report, and no comment. GitHub runs a `workflow_run` workflow only
362
223
  from your default branch, so the pull request that adds the workflow
363
224
  gets no comment.
@@ -375,7 +236,8 @@ name: Perf comment
375
236
  # the pull request's code, and of what the Duel job kept (where that code
376
237
  # ran), it trusts only what that job could have said: the pull request's
377
238
  # number, if it names the pull request the run compared, and the comment
378
- # and the status, if they're ones Duel says. (The workflow must be on the
239
+ # and the status, if they're ones Duel says. A fork's report, which the
240
+ # fork's code wrote, is shown as text. (The workflow must be on the
379
241
  # default branch before it runs at all.)
380
242
  on:
381
243
  workflow_run:
@@ -413,14 +275,29 @@ jobs:
413
275
  COMMENT=$(said comment 'post|change')
414
276
  STATUS=$(said status 'passed|failed|neutral')
415
277
  [ -n "$PR" ] && [ -n "$COMMENT" ] && [ -n "$STATUS" ] || exit 0
416
- [ "$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR" --jq .head.sha)" = "$HEAD_SHA" ] || exit 0
278
+ # (The pull request's head commit, and the repository it's from.)
279
+ head=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR" --jq '"\(.head.sha) \(.head.repo.full_name)"')
280
+ [ "${head%% *}" = "$HEAD_SHA" ] || exit 0
281
+ # The report, as Markdown for a branch of this repository (whose
282
+ # author can push here anyway), but for a fork's, as text: its run
283
+ # ran the fork's code, which could have written anything in it. In
284
+ # a code block, fenced with more backticks than any run of them in
285
+ # the report, it can't mention anyone, link anywhere or show an
286
+ # image. (And it's cut short where a comment couldn't hold it.)
287
+ report() {
288
+ if [ "${head#* }" = "$GITHUB_REPOSITORY" ]; then cat "$RUNNER_TEMP/report/duel.md" && return; fi
289
+ fence=$(grep -o '``*' "$RUNNER_TEMP/report/duel.md" | awk '{ if (length > n) n = length } END { n = (n < 3) ? 3 : n + 1; while (n-- > 0) printf "`" }')
290
+ printf 'From a fork, so shown as text:\n\n%s\n' "$fence"
291
+ head -c 60000 "$RUNNER_TEMP/report/duel.md"
292
+ printf '\n%s\n' "$fence"
293
+ }
417
294
  marker="<!-- duel"
418
295
  # The first line of the last comment Duel posted here: its marker,
419
296
  # with its status (none in Duel 0.1.0's, which counts as another).
420
297
  last=$(gh api --paginate "repos/$GITHUB_REPOSITORY/issues/$PR/comments" \
421
298
  --jq ".[] | select(.user.login == \"github-actions[bot]\") | .body | split(\"\n\")[0] | rtrimstr(\"\r\") | select(startswith(\"$marker status=\") or . == \"$marker -->\")" | tail -n 1)
422
299
  if [ "$COMMENT" = post ] || { [ -n "$last" ] && [ "$last" != "$marker status=$STATUS -->" ]; }; then
423
- { echo "$marker status=$STATUS -->"; cat "$RUNNER_TEMP/report/duel.md"; } > "$RUNNER_TEMP/comment.md"
300
+ { echo "$marker status=$STATUS -->"; report; } > "$RUNNER_TEMP/comment.md"
424
301
  gh api --method POST "repos/$GITHUB_REPOSITORY/issues/$PR/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
425
302
  fi
426
303
  ```
@@ -441,6 +318,52 @@ By default, a push gets no comment: Duel sets the `comment` output to
441
318
  the commit job checks nothing out either, and it alone gets the
442
319
  `contents: write` permission that a commit comment takes.
443
320
 
321
+ `duel init` writes the Comment on the commit job only where `.duel.rb`
322
+ sets `c.fail_on = :pull_requests`, as it's the only time Duel says to
323
+ comment on a push, and the job's `contents: write` is otherwise unused.
324
+ To add it later, set `c.fail_on`, remove the workflow, and run
325
+ `duel init` again (it keeps `.duel.rb`), or add the job yourself:
326
+
327
+ ```yaml
328
+ # .github/workflows/perf.yml, in jobs: (with c.fail_on = :pull_requests)
329
+ # The report, as a new comment on a pushed commit, which notifies its
330
+ # author, when Duel says to, as for a pull request (see the Perf comment
331
+ # workflow). It does only where a regression in a push passes, with
332
+ # c.fail_on = :pull_requests in .duel.rb, so the comment says what the
333
+ # check doesn't. Its last comment is the last one on any commit. This
334
+ # job checks nothing out and runs none of the code.
335
+ commit-comment:
336
+ name: Comment on the commit
337
+ needs: duel
338
+ if: ${{ !cancelled() && github.event_name == 'push' && (needs.duel.outputs.comment == 'post' || needs.duel.outputs.comment == 'change') }}
339
+ runs-on: ubuntu-latest
340
+ permissions:
341
+ contents: write # to comment on the commit with the report
342
+ steps:
343
+ - name: Get the report
344
+ id: report
345
+ continue-on-error: true # there's none when the Duel job failed before comparing
346
+ uses: actions/download-artifact@v8
347
+ with:
348
+ name: duel-report
349
+ path: ${{ runner.temp }}/report
350
+ - name: Comment on the commit
351
+ if: steps.report.outcome == 'success'
352
+ env:
353
+ GH_TOKEN: ${{ github.token }}
354
+ COMMENT: ${{ needs.duel.outputs.comment }}
355
+ STATUS: ${{ needs.duel.outputs.status }}
356
+ run: |
357
+ marker="<!-- duel"
358
+ last=$(gh api --paginate "repos/$GITHUB_REPOSITORY/comments" \
359
+ --jq ".[] | select(.user.login == \"github-actions[bot]\") | .body | split(\"\n\")[0] | rtrimstr(\"\r\") | select(startswith(\"$marker status=\"))" | tail -n 1)
360
+ if [ "$COMMENT" = post ] || { [ -n "$last" ] && [ "$last" != "$marker status=$STATUS -->" ]; }; then
361
+ { echo "$marker status=$STATUS -->"; cat "$RUNNER_TEMP/report/duel.md"; } > "$RUNNER_TEMP/comment.md"
362
+ gh api --method POST "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
363
+ fi
364
+
365
+ ```
366
+
444
367
  ## Accept a regression with a label
445
368
 
446
369
  With [`c.accept_label`](configuration.md#accept-a-regression-with-a-label),
@@ -496,11 +419,75 @@ If you set `c.push_base` back to `:before`, delete the branches too
496
419
  (`git push origin --delete duel/passed/main`), because the step that
497
420
  finds the baseline's Ruby uses one whenever it exists.
498
421
 
422
+ `duel init` writes the Mark the commit passed job only where `.duel.rb`
423
+ sets `c.push_base = :last_passed`, as the job's `contents: write` is
424
+ otherwise unused. To add it later, set `c.push_base`, remove the
425
+ workflow, and run `duel init` again (it keeps `.duel.rb`), or add the job
426
+ yourself:
427
+
428
+ ```yaml
429
+ # .github/workflows/perf.yml, in jobs: (with c.push_base = :last_passed)
430
+ # With c.push_base = :last_passed in .duel.rb, a push is compared with
431
+ # the last commit Duel passed, which a branch marks (each branch pushed
432
+ # has its own), so slowdowns too small for any one push to fail add up
433
+ # until they fail one. This job moves the branch to a push that passed
434
+ # (or makes it), but never back: where a newer push's run moved it
435
+ # first, it stays. It checks nothing out and runs none of the code. To
436
+ # accept a regression, move the branch yourself (for main, git push
437
+ # origin main:duel/passed/main).
438
+ passed:
439
+ name: Mark the commit passed
440
+ needs: duel
441
+ if: ${{ !cancelled() && github.event_name == 'push' && needs.duel.outputs.passed == 'true' }}
442
+ runs-on: ubuntu-latest
443
+ permissions:
444
+ contents: write # to move the branch
445
+ steps:
446
+ - name: Move the branch to the commit
447
+ env:
448
+ GH_TOKEN: ${{ github.token }}
449
+ BRANCH: duel/passed/${{ github.ref_name }}
450
+ run: |
451
+ # (Git can't make a branch where another's name is a folder of its
452
+ # name: a branch named duel blocks duel/passed/main. If one does,
453
+ # this names it.)
454
+ blocked() {
455
+ prefix=$BRANCH
456
+ while [ "${prefix%/*}" != "$prefix" ]; do
457
+ prefix=${prefix%/*}
458
+ if gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$prefix" > /dev/null 2>&1; then
459
+ echo "::error::The branch $prefix keeps Duel from making $BRANCH, as Git can't have both. Delete it (git push origin --delete $prefix), or rename it."
460
+ fi
461
+ done
462
+ exit 1
463
+ }
464
+ # (Forward: GitHub moves it only where it's behind the push.)
465
+ gh api --method PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$GITHUB_SHA" > /dev/null 2>&1 && exit 0
466
+ at=$(gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$BRANCH" --jq .object.sha 2>/dev/null) || at=
467
+ if [ -z "$at" ]; then
468
+ gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$GITHUB_SHA" > /dev/null || blocked
469
+ exit 0
470
+ fi
471
+ compared=$(gh api "repos/$GITHUB_REPOSITORY/compare/$GITHUB_SHA...$at" --jq .status 2>&1) || case "$compared" in
472
+ # (GitHub can't compare commits with no history in common.)
473
+ *"No common ancestor"*) compared=unrelated ;;
474
+ esac
475
+ case "$compared" in
476
+ # (A newer push's run moved it, or this one's did, run again.)
477
+ ahead | identical) ;;
478
+ # (History rewritten, a force push's, say, or replaced: moved anyway.)
479
+ diverged | behind | unrelated) gh api --method PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$GITHUB_SHA" -F force=true > /dev/null ;;
480
+ *) echo "::error::Couldn't compare $BRANCH with this push: $compared" && exit 1 ;;
481
+ esac
482
+
483
+ ```
484
+
499
485
  ## Show whether the last push passed
500
486
 
501
- The Update the badge job keeps a badge that turns red when Duel fails.
502
- After each push to your default branch, it writes `badge.svg` to a
503
- branch of its own, `duel/badge`, so your README can show it:
487
+ With `--badge`, `duel init` adds the Update the badge job, which keeps a
488
+ badge that turns red when Duel fails. After each push to your default
489
+ branch, it writes `badge.svg` to a branch of its own, `duel/badge`, so
490
+ your README can show it:
504
491
 
505
492
  ```markdown
506
493
  [![Duel](https://raw.githubusercontent.com/OWNER/REPO/duel/badge/badge.svg)](https://github.com/sferik/duel-ruby)
@@ -519,8 +506,124 @@ that moving a branch takes. For a project in a subdirectory of its
519
506
  repository, the branch names the directory, such as
520
507
  `duel/badge-gems-parser`.
521
508
 
522
- Until the first push to your default branch after you add the
523
- workflow, the branch doesn't exist, and the badge doesn't show.
509
+ Until the first push to your default branch after you add the job, the
510
+ branch doesn't exist, and the badge doesn't show.
511
+
512
+ `duel init` writes the job only with `--badge` (for a Rails app,
513
+ `bin/rails generate duel:install --badge`), as without the jobs for
514
+ pushes, it's the workflow's only job that writes to the repository. To
515
+ add it later, remove the workflow, and run `duel init --badge` again (it
516
+ keeps `.duel.rb`), or add the job yourself:
517
+
518
+ ```yaml
519
+ # .github/workflows/perf.yml, in jobs: (with duel init --badge)
520
+ # Duel's badge, for the README: green (perf guarded) or red (perf
521
+ # regressed), as the last push to the default branch that Duel compared
522
+ # left it. It's red where the Duel job failed or found a regression,
523
+ # even one that passed (with c.fail_on = :pull_requests in .duel.rb). A
524
+ # push with nothing to compare leaves it as it was, and so does a run
525
+ # for an older push than the badge's. This job writes the badge, alone,
526
+ # to a branch of its own, which the README shows:
527
+ #
528
+ # [![Duel](https://raw.githubusercontent.com/OWNER/REPO/duel/badge/badge.svg)](https://github.com/sferik/duel-ruby)
529
+ #
530
+ # It checks nothing out, runs none of the code, and fetches nothing.
531
+ badge:
532
+ name: Update the badge
533
+ needs: duel
534
+ # One at a time, so that one run's check of which push the badge
535
+ # shows can't interleave with another run's write (a push's run
536
+ # doesn't wait for the one before it). A badge job that's running is
537
+ # never cancelled, and one that's waiting gives way to a newer push's,
538
+ # whose result the badge should show anyway.
539
+ concurrency:
540
+ group: ${{ github.workflow }}-badge
541
+ cancel-in-progress: false
542
+ if: ${{ !cancelled() && github.event_name == 'push' && github.ref_name == github.event.repository.default_branch && (needs.duel.result == 'failure' || needs.duel.outputs.status == 'passed' || needs.duel.outputs.status == 'failed') }}
543
+ runs-on: ubuntu-latest
544
+ permissions:
545
+ contents: write # to move the badge's branch
546
+ steps:
547
+ - name: Update the badge
548
+ env:
549
+ GH_TOKEN: ${{ github.token }}
550
+ BRANCH: duel/badge
551
+ RESULT: ${{ needs.duel.result }}
552
+ STATUS: ${{ needs.duel.outputs.status }}
553
+ run: |
554
+ # (Git can't make a branch where another's name is a folder of its
555
+ # name: a branch named duel blocks duel/passed/main. If one does,
556
+ # this names it.)
557
+ blocked() {
558
+ prefix=$BRANCH
559
+ while [ "${prefix%/*}" != "$prefix" ]; do
560
+ prefix=${prefix%/*}
561
+ if gh api "repos/$GITHUB_REPOSITORY/git/ref/heads/$prefix" > /dev/null 2>&1; then
562
+ echo "::error::The branch $prefix keeps Duel from making $BRANCH, as Git can't have both. Delete it (git push origin --delete $prefix), or rename it."
563
+ fi
564
+ done
565
+ exit 1
566
+ }
567
+ # (Where the badge is a newer push's, that push's run has the say.
568
+ # Its commit names the push.)
569
+ last=$(gh api "repos/$GITHUB_REPOSITORY/commits/$BRANCH" --jq .commit.message 2>/dev/null | sed -n 's/^Duel.s badge, for \([0-9a-f]*\)$/\1/p') || true
570
+ if [ -n "$last" ] && [ "$(gh api "repos/$GITHUB_REPOSITORY/compare/$GITHUB_SHA...$last" --jq .status 2>/dev/null)" = ahead ]; then exit 0; fi
571
+ # (Its image, written here rather than fetched from anywhere: green,
572
+ # or red where the Duel job failed or found a regression.)
573
+ state="perf guarded" width=133 top="#34D058" bottom="#28A745" right="76.939C78.629 0 80 1.343 80"
574
+ if [ "$RESULT" = failure ] || [ "$STATUS" = failed ]; then
575
+ state="perf regressed" width=142 top="#EA4A5A" bottom="#D73A49" right="85.939C87.629 0 89 1.343 89"
576
+ fi
577
+ cat > "$RUNNER_TEMP/badge.svg" <<SVG
578
+ <svg xmlns="http://www.w3.org/2000/svg" width="$width" height="20">
579
+ <title>Duel - $state</title>
580
+ <defs>
581
+ <linearGradient id="duel-fill" x1="50%" y1="0%" x2="50%" y2="100%">
582
+ <stop stop-color="#444D56" offset="0%"></stop>
583
+ <stop stop-color="#24292E" offset="100%"></stop>
584
+ </linearGradient>
585
+ <linearGradient id="state-fill" x1="50%" y1="0%" x2="50%" y2="100%">
586
+ <stop stop-color="$top" offset="0%"></stop>
587
+ <stop stop-color="$bottom" offset="100%"></stop>
588
+ </linearGradient>
589
+ </defs>
590
+ <g fill="none" fill-rule="evenodd">
591
+ <g font-family="'DejaVu Sans',Verdana,Geneva,sans-serif" font-size="11">
592
+ <path d="M0,3 C0,1.3431 1.3552,0 3.02702703,0 L53,0 L53,20 L3.02702703,20 C1.3552,20 0,18.6569 0,17 L0,3 Z" fill="url(#duel-fill)" fill-rule="nonzero"></path>
593
+ <text fill="#010101" fill-opacity=".3">
594
+ <tspan x="22.1981982" y="15" aria-hidden="true">Duel</tspan>
595
+ </text>
596
+ <text fill="#FFFFFF">
597
+ <tspan x="22.1981982" y="14">Duel</tspan>
598
+ </text>
599
+ </g>
600
+ <g transform="translate(53)" font-family="'DejaVu Sans',Verdana,Geneva,sans-serif" font-size="11">
601
+ <path d="M0 0h$right 3v14c0 1.657-1.37 3-3.061 3H0V0z" fill="url(#state-fill)" fill-rule="nonzero"></path>
602
+ <text fill="#010101" fill-opacity=".3" aria-hidden="true">
603
+ <tspan x="4" y="15">$state</tspan>
604
+ </text>
605
+ <text fill="#FFFFFF">
606
+ <tspan x="4" y="14">$state</tspan>
607
+ </text>
608
+ </g>
609
+ <g fill="#959DA5">
610
+ <path d="M4.6 3.6L6.9 4.5L14.3 11.9L12.9 13.3L5.5 5.9Z M17.4 3.6L15.1 4.5L7.7 11.9L9.1 13.3L16.5 5.9Z"></path>
611
+ <circle cx="16.6" cy="15.6" r="1.1"></circle>
612
+ <circle cx="5.4" cy="15.6" r="1.1"></circle>
613
+ </g>
614
+ <g stroke="#959DA5" stroke-linecap="round">
615
+ <path d="M12.1 14.5L15.5 11.1 M9.9 14.5L6.5 11.1" stroke-width="1.6"></path>
616
+ <path d="M13.8 12.8L16 15 M8.2 12.8L6 15" stroke-width="1.8"></path>
617
+ </g>
618
+ </g>
619
+ </svg>
620
+ SVG
621
+ tree=$(jq -n --rawfile svg "$RUNNER_TEMP/badge.svg" '{tree: [{path: "badge.svg", mode: "100644", type: "blob", content: $svg}]}' |
622
+ gh api --method POST "repos/$GITHUB_REPOSITORY/git/trees" --input - --jq .sha)
623
+ commit=$(gh api --method POST "repos/$GITHUB_REPOSITORY/git/commits" -f message="Duel's badge, for $GITHUB_SHA" -f tree="$tree" --jq .sha)
624
+ gh api --method PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$commit" -F force=true > /dev/null 2>&1 ||
625
+ gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$commit" > /dev/null || blocked
626
+ ```
524
627
 
525
628
  ## Guard other branches
526
629
 
@@ -145,7 +145,10 @@ pull request's Checks tab). For a push, Duel reads the labels of the
145
145
  pull request that merged it, so with
146
146
  [`c.push_base = :last_passed`](#compare-a-push-with-the-last-commit-that-passed),
147
147
  the merged regression becomes the commit that later pushes are compared
148
- with. By default, there's no such label.
148
+ with. Duel's default is no such label, but the `.duel.rb` that
149
+ `duel init` writes (and duel-rails's generator) names `duel: accept`.
150
+ Create the label in your repository to use it, or set
151
+ `c.accept_label = nil` so that nothing can let a regression through.
149
152
 
150
153
  ## Compare a push with the last commit that passed
151
154
 
data/lib/duel/init.rb CHANGED
@@ -11,7 +11,8 @@ module Duel
11
11
  # `duel init`: sets Duel up in a gem or an app that isn't a Rails app
12
12
  # (duel-rails's generator sets a Rails app up). It writes .duel.rb, a
13
13
  # benchmark to start from, and GitHub Actions workflows (Duel's, and
14
- # one that comments on a pull request with its report), or with
14
+ # one that comments on a pull request with its report, and with --badge
15
+ # a job that keeps a badge), or with
15
16
  # --gitlab, GitLab CI jobs to include, adds a Rake
16
17
  # task to the Rakefile, and adds StackProf to the Gemfile (for profiles
17
18
  # of regressions, on CRuby). It overwrites nothing without --force, and
@@ -79,6 +80,7 @@ module Duel
79
80
  o.banner = USAGE
80
81
  o.on("--force", "Overwrite files that exist") { @force = true }
81
82
  o.on("--dry-run", "Say what it would do, and write nothing") { @dry_run = true }
83
+ o.on("--badge", "Write a job that keeps a badge for the README (it needs contents: write)") { @badge = true }
82
84
  o.on("--gitlab", "Write GitLab CI jobs (to include from .gitlab-ci.yml), not GitHub Actions workflows") { @gitlab = true }
83
85
  o.on("-h", "--help", "Print this help") do
84
86
  @out.puts o
@@ -179,6 +181,42 @@ module Duel
179
181
  # The project's configuration, as the conventions have it.
180
182
  def config = Config.new(@root)
181
183
 
184
+ # The project's settings, which decide the workflow's jobs: its
185
+ # .duel.rb's, or the defaults, where there's none yet or --force
186
+ # replaces it with the one it writes. Nil where it doesn't load (one
187
+ # of its plugins isn't installed, say), and then the workflow has
188
+ # both jobs for pushes, as if .duel.rb asked for them, and says so.
189
+ def settings = instance_variable_defined?(:@settings) ? @settings : (@settings = load_settings)
190
+
191
+ def load_settings
192
+ path = File.join(@root, ".duel.rb")
193
+ return Config.new if @force || !File.exist?(path)
194
+
195
+ Duel.load_config(path)
196
+ rescue ScriptError, StandardError => e
197
+ @err.puts "duel init: .duel.rb didn't load (#{e.class}: #{e}), so the workflow has both jobs for pushes, as if it asked for them"
198
+ end
199
+
200
+ # Whether the workflow comments on a pushed commit: where a regression
201
+ # in a push passes (c.fail_on = :pull_requests), the only time Duel
202
+ # says to.
203
+ def comment_on_pushes?
204
+ found = settings
205
+ found.nil? || found.fail_on == :pull_requests
206
+ end
207
+
208
+ # Whether the workflow marks a push passed: where a push is compared
209
+ # with the last commit Duel passed (c.push_base = :last_passed).
210
+ def mark_passed?
211
+ found = settings
212
+ found.nil? || found.push_base == :last_passed
213
+ end
214
+
215
+ # Whether the workflow keeps a badge for the README (--badge): its job
216
+ # moves a branch, so it's the workflow's only job, without the jobs
217
+ # for pushes, that writes to the repository.
218
+ def badge? = @badge
219
+
182
220
  # The library the gemspec names (see Config#library), or nil.
183
221
  def library = config.library
184
222
 
@@ -1,7 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  require "rake"
4
- require_relative "cli"
5
4
 
6
5
  module Duel
7
6
  # A rake task running `duel` with +args+:
@@ -9,12 +8,22 @@ module Duel
9
8
  # require "duel/rake_task"
10
9
  # Duel::RakeTask.new(:perf)
11
10
  # Duel::RakeTask.new(:perf_since_release, "--base", "last-release")
11
+ #
12
+ # Duel itself loads only as the task runs: a Rakefile that defines the
13
+ # task loads nothing more for its other tasks (rake test, say).
12
14
  class RakeTask
13
15
  include Rake::DSL
14
16
 
17
+ # Loads Duel's command, as the task runs.
18
+ # mutant:disable -- the tests' process has Duel loaded from the start, so
19
+ # a require changes nothing there: RakeTaskTest's
20
+ # test_the_task_loads_duel_as_it_runs checks it, in a process of its own
21
+ def self.load_duel = require_relative("cli")
22
+
15
23
  def initialize(name = :duel, *args)
16
24
  desc "Fail if this tree is slower than its baseline at any benchmark (duel)"
17
25
  task(name) do
26
+ RakeTask.load_duel
18
27
  case CLI.new(args).run
19
28
  when 1 then abort "duel: slower than the baseline"
20
29
  when 2 then abort "duel: couldn't compare"
@@ -40,14 +40,18 @@ Duel.configure do |c|
40
40
 
41
41
  # Which runs a regression fails: :every_run, or :pull_requests, for a
42
42
  # project where people push to main directly (on GitHub Actions, another
43
- # run warns and passes, and a pushed commit gets the comment instead).
43
+ # run warns and passes, and a pushed commit gets the comment instead,
44
+ # from a workflow job written only where this is set: see docs/ci.md).
44
45
  # c.fail_on = :every_run
45
46
 
46
- # A label that accepts a regression in a pull request (nil for none).
47
- # c.accept_label = "duel: accept"
47
+ # A label that accepts a regression in a pull request, for a change
48
+ # that's slower on purpose (nil for none).
49
+ c.accept_label = "duel: accept"
48
50
 
49
51
  # What the workflow compares a push with: :before (the commit before it),
50
52
  # or :last_passed (the last commit Duel passed, which a branch,
51
53
  # duel/passed/main, marks), so small slowdowns add up until they fail.
54
+ # (A workflow job moves the branch, written only where this is set: see
55
+ # docs/ci.md.)
52
56
  # c.push_base = :before
53
57
  end
@@ -9,7 +9,8 @@ name: Perf comment<%= " (#{working_directory})" if working_directory %>
9
9
  # the pull request's code, and of what the Duel job kept (where that code
10
10
  # ran), it trusts only what that job could have said: the pull request's
11
11
  # number, if it names the pull request the run compared, and the comment
12
- # and the status, if they're ones Duel says. (The workflow must be on the
12
+ # and the status, if they're ones Duel says. A fork's report, which the
13
+ # fork's code wrote, is shown as text. (The workflow must be on the
13
14
  # default branch before it runs at all.)
14
15
  on:
15
16
  workflow_run:
@@ -47,13 +48,28 @@ jobs:
47
48
  COMMENT=$(said comment 'post|change')
48
49
  STATUS=$(said status 'passed|failed|neutral')
49
50
  [ -n "$PR" ] && [ -n "$COMMENT" ] && [ -n "$STATUS" ] || exit 0
50
- [ "$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR" --jq .head.sha)" = "$HEAD_SHA" ] || exit 0
51
+ # (The pull request's head commit, and the repository it's from.)
52
+ head=$(gh api "repos/$GITHUB_REPOSITORY/pulls/$PR" --jq '"\(.head.sha) \(.head.repo.full_name)"')
53
+ [ "${head%% *}" = "$HEAD_SHA" ] || exit 0
54
+ # The report, as Markdown for a branch of this repository (whose
55
+ # author can push here anyway), but for a fork's, as text: its run
56
+ # ran the fork's code, which could have written anything in it. In
57
+ # a code block, fenced with more backticks than any run of them in
58
+ # the report, it can't mention anyone, link anywhere or show an
59
+ # image. (And it's cut short where a comment couldn't hold it.)
60
+ report() {
61
+ if [ "${head#* }" = "$GITHUB_REPOSITORY" ]; then cat "$RUNNER_TEMP/report/duel.md" && return; fi
62
+ fence=$(grep -o '``*' "$RUNNER_TEMP/report/duel.md" | awk '{ if (length > n) n = length } END { n = (n < 3) ? 3 : n + 1; while (n-- > 0) printf "`" }')
63
+ printf 'From a fork, so shown as text:\n\n%s\n' "$fence"
64
+ head -c 60000 "$RUNNER_TEMP/report/duel.md"
65
+ printf '\n%s\n' "$fence"
66
+ }
51
67
  marker="<!-- <%= marker %>"
52
68
  # The first line of the last comment Duel posted here: its marker,
53
69
  # with its status (none in Duel 0.1.0's, which counts as another).
54
70
  last=$(gh api --paginate "repos/$GITHUB_REPOSITORY/issues/$PR/comments" \
55
71
  --jq ".[] | select(.user.login == \"github-actions[bot]\") | .body | split(\"\n\")[0] | rtrimstr(\"\r\") | select(startswith(\"$marker status=\") or . == \"$marker -->\")" | tail -n 1)
56
72
  if [ "$COMMENT" = post ] || { [ -n "$last" ] && [ "$last" != "$marker status=$STATUS -->" ]; }; then
57
- { echo "$marker status=$STATUS -->"; cat "$RUNNER_TEMP/report/duel.md"; } > "$RUNNER_TEMP/comment.md"
73
+ { echo "$marker status=$STATUS -->"; report; } > "$RUNNER_TEMP/comment.md"
58
74
  gh api --method POST "repos/$GITHUB_REPOSITORY/issues/$PR/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
59
75
  fi
@@ -173,6 +173,7 @@ jobs:
173
173
  path: ${{ runner.temp }}/duel/
174
174
  if-no-files-found: ignore # none when Duel didn't get to compare
175
175
  retention-days: 1
176
+ <% if comment_on_pushes? -%>
176
177
 
177
178
  # The report, as a new comment on a pushed commit, which notifies its
178
179
  # author, when Duel says to, as for a pull request (see the Perf comment
@@ -209,6 +210,8 @@ jobs:
209
210
  { echo "$marker status=$STATUS -->"; cat "$RUNNER_TEMP/report/duel.md"; } > "$RUNNER_TEMP/comment.md"
210
211
  gh api --method POST "repos/$GITHUB_REPOSITORY/commits/$GITHUB_SHA/comments" -F body=@"$RUNNER_TEMP/comment.md" > /dev/null
211
212
  fi
213
+ <% end -%>
214
+ <% if mark_passed? -%>
212
215
 
213
216
  # With c.push_base = :last_passed in .duel.rb, a push is compared with
214
217
  # the last commit Duel passed, which a branch marks (each branch pushed
@@ -262,6 +265,8 @@ jobs:
262
265
  diverged | behind | unrelated) gh api --method PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$GITHUB_SHA" -F force=true > /dev/null ;;
263
266
  *) echo "::error::Couldn't compare $BRANCH with this push: $compared" && exit 1 ;;
264
267
  esac
268
+ <% end -%>
269
+ <% if badge? -%>
265
270
 
266
271
  # Duel's badge, for the README: green (perf guarded) or red (perf
267
272
  # regressed), as the last push to the default branch that Duel compared
@@ -273,10 +278,18 @@ jobs:
273
278
  #
274
279
  # [![Duel](https://raw.githubusercontent.com/OWNER/REPO/<%= badge_branch %>/badge.svg)](https://github.com/sferik/duel-ruby)
275
280
  #
276
- # It checks nothing out and runs none of the code.
281
+ # It checks nothing out, runs none of the code, and fetches nothing.
277
282
  badge:
278
283
  name: Update the badge
279
284
  needs: duel
285
+ # One at a time, so that one run's check of which push the badge
286
+ # shows can't interleave with another run's write (a push's run
287
+ # doesn't wait for the one before it). A badge job that's running is
288
+ # never cancelled, and one that's waiting gives way to a newer push's,
289
+ # whose result the badge should show anyway.
290
+ concurrency:
291
+ group: ${{ github.workflow }}-badge
292
+ cancel-in-progress: false
280
293
  if: ${{ !cancelled() && github.event_name == 'push' && github.ref_name == github.event.repository.default_branch && (needs.duel.result == 'failure' || needs.duel.outputs.status == 'passed' || needs.duel.outputs.status == 'failed') }}
281
294
  runs-on: ubuntu-latest
282
295
  permissions:
@@ -288,7 +301,6 @@ jobs:
288
301
  BRANCH: <%= badge_branch %>
289
302
  RESULT: ${{ needs.duel.result }}
290
303
  STATUS: ${{ needs.duel.outputs.status }}
291
- BADGES: https://raw.githubusercontent.com/sferik/duel-ruby/main/assets
292
304
  run: |
293
305
  # (Git can't make a branch where another's name is a folder of its
294
306
  # name: a branch named duel blocks duel/passed/main. If one does,
@@ -307,11 +319,59 @@ jobs:
307
319
  # Its commit names the push.)
308
320
  last=$(gh api "repos/$GITHUB_REPOSITORY/commits/$BRANCH" --jq .commit.message 2>/dev/null | sed -n 's/^Duel.s badge, for \([0-9a-f]*\)$/\1/p') || true
309
321
  if [ -n "$last" ] && [ "$(gh api "repos/$GITHUB_REPOSITORY/compare/$GITHUB_SHA...$last" --jq .status 2>/dev/null)" = ahead ]; then exit 0; fi
310
- badge="badge.svg"
311
- if [ "$RESULT" = failure ] || [ "$STATUS" = failed ]; then badge="badge-regressed.svg"; fi
312
- curl -fsSL "$BADGES/$badge" -o "$RUNNER_TEMP/badge.svg"
322
+ # (Its image, written here rather than fetched from anywhere: green,
323
+ # or red where the Duel job failed or found a regression.)
324
+ state="perf guarded" width=133 top="#34D058" bottom="#28A745" right="76.939C78.629 0 80 1.343 80"
325
+ if [ "$RESULT" = failure ] || [ "$STATUS" = failed ]; then
326
+ state="perf regressed" width=142 top="#EA4A5A" bottom="#D73A49" right="85.939C87.629 0 89 1.343 89"
327
+ fi
328
+ cat > "$RUNNER_TEMP/badge.svg" <<SVG
329
+ <svg xmlns="http://www.w3.org/2000/svg" width="$width" height="20">
330
+ <title>Duel - $state</title>
331
+ <defs>
332
+ <linearGradient id="duel-fill" x1="50%" y1="0%" x2="50%" y2="100%">
333
+ <stop stop-color="#444D56" offset="0%"></stop>
334
+ <stop stop-color="#24292E" offset="100%"></stop>
335
+ </linearGradient>
336
+ <linearGradient id="state-fill" x1="50%" y1="0%" x2="50%" y2="100%">
337
+ <stop stop-color="$top" offset="0%"></stop>
338
+ <stop stop-color="$bottom" offset="100%"></stop>
339
+ </linearGradient>
340
+ </defs>
341
+ <g fill="none" fill-rule="evenodd">
342
+ <g font-family="'DejaVu Sans',Verdana,Geneva,sans-serif" font-size="11">
343
+ <path d="M0,3 C0,1.3431 1.3552,0 3.02702703,0 L53,0 L53,20 L3.02702703,20 C1.3552,20 0,18.6569 0,17 L0,3 Z" fill="url(#duel-fill)" fill-rule="nonzero"></path>
344
+ <text fill="#010101" fill-opacity=".3">
345
+ <tspan x="22.1981982" y="15" aria-hidden="true">Duel</tspan>
346
+ </text>
347
+ <text fill="#FFFFFF">
348
+ <tspan x="22.1981982" y="14">Duel</tspan>
349
+ </text>
350
+ </g>
351
+ <g transform="translate(53)" font-family="'DejaVu Sans',Verdana,Geneva,sans-serif" font-size="11">
352
+ <path d="M0 0h$right 3v14c0 1.657-1.37 3-3.061 3H0V0z" fill="url(#state-fill)" fill-rule="nonzero"></path>
353
+ <text fill="#010101" fill-opacity=".3" aria-hidden="true">
354
+ <tspan x="4" y="15">$state</tspan>
355
+ </text>
356
+ <text fill="#FFFFFF">
357
+ <tspan x="4" y="14">$state</tspan>
358
+ </text>
359
+ </g>
360
+ <g fill="#959DA5">
361
+ <path d="M4.6 3.6L6.9 4.5L14.3 11.9L12.9 13.3L5.5 5.9Z M17.4 3.6L15.1 4.5L7.7 11.9L9.1 13.3L16.5 5.9Z"></path>
362
+ <circle cx="16.6" cy="15.6" r="1.1"></circle>
363
+ <circle cx="5.4" cy="15.6" r="1.1"></circle>
364
+ </g>
365
+ <g stroke="#959DA5" stroke-linecap="round">
366
+ <path d="M12.1 14.5L15.5 11.1 M9.9 14.5L6.5 11.1" stroke-width="1.6"></path>
367
+ <path d="M13.8 12.8L16 15 M8.2 12.8L6 15" stroke-width="1.8"></path>
368
+ </g>
369
+ </g>
370
+ </svg>
371
+ SVG
313
372
  tree=$(jq -n --rawfile svg "$RUNNER_TEMP/badge.svg" '{tree: [{path: "badge.svg", mode: "100644", type: "blob", content: $svg}]}' |
314
373
  gh api --method POST "repos/$GITHUB_REPOSITORY/git/trees" --input - --jq .sha)
315
374
  commit=$(gh api --method POST "repos/$GITHUB_REPOSITORY/git/commits" -f message="Duel's badge, for $GITHUB_SHA" -f tree="$tree" --jq .sha)
316
375
  gh api --method PATCH "repos/$GITHUB_REPOSITORY/git/refs/heads/$BRANCH" -f sha="$commit" -F force=true > /dev/null 2>&1 ||
317
376
  gh api --method POST "repos/$GITHUB_REPOSITORY/git/refs" -f ref="refs/heads/$BRANCH" -f sha="$commit" > /dev/null || blocked
377
+ <% end -%>
data/lib/duel/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Duel
4
- VERSION = "0.1.4"
4
+ VERSION = "0.1.5"
5
5
  end
data/sig/duel/init.rbs CHANGED
@@ -22,6 +22,8 @@ module Duel
22
22
  @force: bool?
23
23
  @dry_run: bool?
24
24
  @gitlab: bool?
25
+ @badge: bool?
26
+ @settings: Config?
25
27
  @stackprof: bool?
26
28
 
27
29
  def initialize: (Array[String] argv, ?out: _Output, ?err: _Output, ?root: String) -> void
@@ -67,6 +69,18 @@ module Duel
67
69
  # The project's configuration, as the conventions have it.
68
70
  def config: () -> Config
69
71
 
72
+ # The project's settings, which decide the workflow's jobs (nil where
73
+ # .duel.rb doesn't load).
74
+ def settings: () -> Config?
75
+
76
+ def load_settings: () -> Config?
77
+
78
+ # Whether the workflow comments on a pushed commit.
79
+ def comment_on_pushes?: () -> bool
80
+
81
+ # Whether the workflow marks a push passed.
82
+ def mark_passed?: () -> bool
83
+
70
84
  # The library the gemspec names, or nil.
71
85
  def library: () -> String?
72
86
 
@@ -104,6 +118,9 @@ module Duel
104
118
  # The branch that marks the last commit Duel passed in a push.
105
119
  def passed_branch: () -> String
106
120
 
121
+ # Whether the workflow keeps a badge for the README (--badge).
122
+ def badge?: () -> bool?
123
+
107
124
  # The branch that holds the workflow's badge.
108
125
  def badge_branch: () -> String
109
126
 
@@ -4,6 +4,9 @@ module Duel
4
4
  # Duel::RakeTask.new(:perf)
5
5
  # Duel::RakeTask.new(:perf_since_release, "--base", "last-release")
6
6
  class RakeTask
7
+ # Loads Duel's command, as the task runs.
8
+ def self.load_duel: () -> bool
9
+
7
10
  def initialize: (?Symbol | String name, *String args) -> void
8
11
  end
9
12
  end
data/sig/duel/runner.rbs CHANGED
@@ -2,7 +2,7 @@ module Duel
2
2
  # Where reports go ($stdout, or a StringIO in its place).
3
3
  # @api private
4
4
  interface _Output
5
- def puts: (*_ToS objects) -> void
5
+ def puts: (*_ToS objects) -> nil
6
6
 
7
7
  def print: (*_ToS objects) -> void
8
8
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: duel
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.1.5
5
5
  platform: ruby
6
6
  authors:
7
7
  - Erik Berlin