Skip to content

Add a line per run to User:ParamBot/ReportHistory - #1

Merged
phuzion merged 2 commits into
mainfrom
report-history
Oct 29, 2026
Merged

phuzion merged 2 commits into
mainfrom
report-history

Conversation

@zackmann08

@zackmann08 zackmann08 commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

After every live or report-only run, ParamBot now adds one line to the top of User:ParamBot/ReportHistory. It works like ZackBotPy's User:ZackBot/DepReport (deprecbot/wikireport.py). User:ParamBot/Report is replaced on every run and only shows the latest one. The history page keeps one row per run, newest first:

Started (UTC) Ended (UTC) Duration Mode Categories Checked Edits Needs review Result

The Result column says how the run ended:

  • finished
  • finished early: <why> (max_edits, max_hours, or the BRFA trial limit)
  • error: <message> (a crash, or a save error that every edit would hit, such as being blocked)
  • stopped: <message> (any other stop after the run had started, such as the trial count failing to save)
  • aborted: [[User:ParamBot/Run]] was changed at <time> by [[User:X|X]], so the run stopped: … This is for a run that someone switches off part way through by editing the Run page. The time and editor come from the Run page's newest revision. If they can't be read, the line just says the page was changed.

When the report page was saved, the row ends with a permalink to that revision of the report.

Example of the page:

{{User:ParamBot/Header}}
A line for every run of [[User:ParamBot|ParamBot]], newest first, except runs that didn't start because [[User:ParamBot/Run]] was off: ...

{| class="wikitable"
! Started (UTC) !! Ended (UTC) !! Duration !! Mode !! Categories !! Checked !! Edits !! Needs review !! Result
<!-- ParamBot: new runs go below this line -->
|-
| 2026-10-27 04:00 || 2026-10-27 04:00 || under a minute || live || 1 of 1 || 2 || 1 || 0 || aborted: [[User:ParamBot/Run]] was changed at 2026-10-27 04:07 by [[User:Some editor|Some editor]], so the run stopped: User:ParamBot/Run no longer says "yes"; stopped before editing Second
|-
| 2026-10-26 22:00 || 2026-10-26 22:12 || 12 minutes || live || 3 of 41 || 57 || 52 || 2 || finished ([[Special:Permalink/123456|report]])
|}

Changes

New: parambot/history.py

  • history_row() builds one row. Its duration uses messages.duration, so it's in the same words as the report's top line ("14 minutes").
  • updated_page() puts the row at the top of the table, below a marker comment. Anything above the marker, such as the intro, can be edited by hand and is kept. A missing or placeholder page is started afresh. Only the newest 200 rows are kept (about 50 days at four runs a day).

parambot/bot.py

  • New RunPageOff(StopRun) exception, raised by _check_run_page, so a Run-page switch-off can be told apart from other stops. Existing except StopRun code still catches it.
  • New _write_history(). It runs after the report is written on every path out of run(): finished, finished early, StopRun, CannotEdit and crashes. It only runs once the pre-flight checks have passed, and only for runs that save the report (live and report-only). It never raises: if the save fails, the failure is logged and the run carries on.
  • New _switched_off_result(), which reads when the Run page was changed and by whom, for the abort line.
  • A report-only run switched off just before saving the report is also recorded as aborted.
  • New _end_early(), which records why a run stopped early (max_edits, max_hours, trial limit) for the history line. Those notes still go on the report too.
  • New _check_history_page() in pre-flight. The history page must be a subpage of User:<bot>, and must not be one of the bot's other pages or a rules page.
  • _check_may_save() now lets a report-only run save the history page as well as the report page. Both must still be in the bot's own userspace.
  • _save_report_page() remembers the saved revision, so the history row can link to it.

Behaviour change on Run-page stops. Until now, after a Run-page switch-off the bot made no more wiki edits at all. It now makes exactly one: the history line in its own userspace, explaining the abort. The report page, the trial log and all articles are still left alone. A run that the Run page stops before it starts adds no line, so a switched-off bot doesn't add four "not running" lines a day.

Settings / CLI / options

  • Options.history_page defaults to User:<bot>/ReportHistory and is listed in other_pages(). So the report page can never replace the history page, and the trial log check excludes it too.
  • New [pages] history setting (settings.py, deploy/parambot.example.toml) and a --history-page option for run (cli.py).
  • The bot creates the history page if it doesn't exist (no nocreate). That is safe because it must be in the bot's own userspace.

parambot/wiki.py

  • New Wiki.last_change(title): (timestamp, user) of a page's newest revision, or None if the page doesn't exist.

parambot/messages.py

  • New history_intro, history_summary, history_elsewhere and run_page_changed. The intro says which runs get a line: every run, except runs that didn't start because the Run page was off.
  • report_only_refused_save now names both pages a report-only run may edit.

Docs

  • README.md: new step 7 in "How a run works", the emergency-stop exception, the --history-page and [pages] history options, and the project layout.
  • docs/operators.md: the page table and the description of each run.
  • docs/documentation.mediawiki: the page table, a new "The report history" section, and the protection table.

Tests

  • New tests/test_history.py: row format, starting a fresh page, newest-first order with hand edits kept, trimming to MAX_ROWS, and that a row's duration is in the report's words.
  • tests/test_bot.py, 17 new whole-run tests:
    • live, report-only and trial rows, with the report permalink
    • two runs give two rows, newest first; dry runs add none
    • an abort mid-run names who changed the Run page and when, and still saves no report
    • an abort is still explained if the Run page's history can't be read
    • a report-only switch-off
    • no row when the bot is switched off before the run starts
    • rows for finishing early, crashes, CannotEdit and other stops
    • a failing history save doesn't break the run
    • pre-flight refuses a history page outside the bot's userspace, or one that clashes with another page
    • report-only may save the history page
  • tests/test_wiki.py: last_change.
  • tests/fakes.py: FakeWiki.last_change. A missing page still comes back as a throwaway FakePage, but it knows its wiki (wiki=), and joins FakeWiki.pages only when it's saved, as a created page does on the real wiki. So every other FakeWiki method sees the same pages as before.

pytest (686 passed), ruff check . and coverage (97%, threshold 95%) all pass. mypy reports the same 15 errors before and after this change, all about missing mwparserfromhell stubs in the local environment.

Not changed

  • docs/header.mediawiki doesn't link the new page, on purpose.
  • The history page is saved without nocreate. Before deploying, either create User:ParamBot/ReportHistory by hand or give the bot password the page-creation grant.

Live and report-only runs now add a row to the top of a report history
page, like ZackBotPy's User:ZackBot/DepReport: when the run started and
ended, its mode, what it did and how it ended. A run aborted because
someone changed User:ParamBot/Run says so, with when and by whom.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XRKwUh3dhUxq1hCdk3gfq1
@phuzion

phuzion commented Oct 29, 2026

Copy link
Copy Markdown
Owner

Thanks for this. The idea is good, the code is in the house style, and the tests cover every way a run can end. Three things to fix before I merge. Each one below says what's wrong, where it is, and what I'd like instead, so it can be worked on without any other context.

Already settled, so please don't change these:

  • The one edit after a Run-page stop is fine. When User:ParamBot/Run is switched off mid-run, the bot still adds its "aborted" row to User:ParamBot/ReportHistory. That's an edit to the bot's own userspace, and we're happy with it.
  • Page creation is handled on our side. The bot password has no page-creation grant at the moment. Before this is deployed, either we'll create User:ParamBot/ReportHistory by hand or we'll add the grant. Leave the history save as it is.
  • No header link. Don't add the history page to docs/header.mediawiki. If we want it there later, we'll add it by hand.

1. Narrow the change to the fake wiki in tests/fakes.py

The PR changes FakeWiki.page() from

return self.pages.get(title) or FakePage(title, exists=False)

to

return self.pages.setdefault(title, FakePage(title, exists=False))

It also makes FakePage.save() set self._exists = True.

What it was for: the bot creates the history page, and the history tests need to find that page afterwards to check what was saved. Before this change, a missing page was a throwaway object, so whatever was saved to it was lost.

Why it's a problem: self.pages is meant to hold only the pages a test set up, plus any page the bot really created. With setdefault, every title the bot merely looks up is stored too, as a "missing" placeholder. So what's in self.pages depends on which pages the bot happened to look at. Other FakeWiki methods assume the old meaning:

  • redirects() breaks. It does self.pages.get(title) or targets.get(title).
    • Some tests (for example the one at tests/test_prepare.py:49) put a redirect target on the wiki only through the redirect, not as a page of its own.
    • If the bot ever calls wiki.page(target) before asking for redirects, a missing placeholder is stored under that title.
    • The placeholder is truthy, so targets.get(title) never runs, and the fake wrongly answers "no redirects".
    • Today's code doesn't happen to call them in that order, so nothing fails yet. A harmless reordering in prepare.py would break it.
  • A missing page is the same object on every lookup. If the bot sets .text on a missing page and then doesn't save it (a dry run, a skipped edit, a save error), a later lookup in the same test sees the changed text. On the real wiki the page would still be missing and empty, so a test could pass on behaviour that fails live.
  • Creation always works in the fake. It doesn't model page-creation rights, so these tests can't catch a create that the real wiki would refuse.

On its own, the setdefault line doesn't break any of main's 650 tests: I checked. It's a trap for later, not a failure now.

What I'd like instead: keep page() as it was on main, and store a missing page only when it's actually saved, as on the real wiki:

  • FakePage.__init__ gets an optional wiki=None argument, stored as self._wiki.
  • FakeWiki.page() returns self.pages.get(title) or FakePage(title, exists=False, wiki=self). Missing pages are still throwaway objects; they just know which wiki to join if they're saved.
  • In FakePage.save(), after the existing nocreate check and the self._exists = True line, add: if self._wiki is not None: self._wiki.pages.setdefault(self._title, self).

Then every FakeWiki method sees the same pages as before, plus any page the bot really created, and the history tests can still find the page the bot made.

If that turns out awkward, an acceptable alternative is to leave page() and save() exactly as they are on main. The history tests then add the history page to the FakeWiki themselves before the run: as an existing page for the "append a row" tests, and as FakePage(title, exists=False) for the "create the page" test. Either way, please run the whole test suite afterwards.

2. Use one duration format, the existing one

parambot/history.py adds its own duration(elapsed: timedelta), which gives "45 s", "12 min", "1 h 38 min" or "2 d 3 h". parambot/messages.py already has duration(seconds: float), which gives "under a minute", "14 minutes" or "2 hours 5 minutes". The report's top line already uses it, through msg.run_times(). So the same run would say "taking 14 minutes" on User:ParamBot/Report and "14 min" on ReportHistory. Two helpers doing one job will drift apart.

Please:

  • Delete duration from history.py, and drop it from history.py's __all__ and from the import in tests/test_history.py.
  • In history_row, use msg.duration((ended - started).total_seconds()), importing messages the way the other modules do (from parambot import messages as msg).
  • Replace test_duration in tests/test_history.py with a test that a row shows the messages-style duration, for example a 14-minute run shows "14 minutes". messages.duration already has its own tests.
  • Check that the docs (docs/documentation.mediawiki, docs/operators.md, README) don't quote the old "12 min" style anywhere.

If a short form really fits the table better, I'm open to it, but then it belongs in messages.py beside duration, with both pages using the same one. I'd rather keep one format.

3. Make the intro match which runs get a row

The intro says the page lists "every run of ParamBot that saved anything". The same wording is in msg.history_intro() in parambot/messages.py, in the module docstring at the top of parambot/history.py, and in the new section of docs/documentation.mediawiki. But that isn't what the code does: _write_history adds a row on every way out of a run after pre-flight, including:

  • runs that crashed before saving anything;
  • runs stopped by a CannotEdit stop code;
  • runs aborted by the Run page, which save nothing else.

The only runs without a row are those switched off before they start, which is deliberate.

Please make all four places describe what actually gets a row, for example: "A line for every run, newest first, except runs that didn't start because User:ParamBot/Run was off." Keep the rest of the Documentation paragraph: the columns, the 200-line limit, and that the text above the table can be edited. Also check that the tests assert the intro text, if any do, and update them to match.


Once these are in, I'm happy to merge. After merging, we'll paste the updated Documentation onto the wiki and set up the history page before the next Toolforge run.

- tests/fakes.py: FakeWiki.page() again returns a throwaway FakePage for
  a missing title; the page joins the wiki only when it's saved, as a
  created page does on a real wiki.
- history.py: drop its own duration(); rows use messages.duration, the
  same words as the report ("14 minutes").
- The intro (messages.history_intro, history.py's docstring, the
  Documentation) now says which runs get a line: every run, except runs
  that didn't start because the Run page was off.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XRKwUh3dhUxq1hCdk3gfq1
@phuzion
phuzion merged commit 683e588 into main Oct 29, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants