Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 18 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,15 @@ replacement.
it names. It ends with a comment naming the git commit of the bot that
wrote it, such as `<!-- ParamBot 24cef13 -->`. It's saved on every run,
so its history is a log of the runs.
7. **Adds a line to the report history,** `User:ParamBot/ReportHistory`, on
live and report-only runs, newest first: when the run started and ended,
how long it took, whether it was live, a BRFA trial or reporting only, how
many categories had pages, and how many pages it checked, edited and left
for review. The last column says how the run ended (finished, finished
early and why, stopped by an error, or aborted by the Run page, saying
when it was changed and by whom), with a permanent link to the report it
saved. The bot creates the page if need be, and keeps the newest 200 lines;
anything above the table can be edited by hand.

## Safeguards

Expand Down Expand Up @@ -133,7 +142,10 @@ is due to expire, or if `User:ParamBot/Rules/Instructions`,
lets a report-only run update the report, but still stops any run that
would edit articles. After that
it makes no more wiki edits, not even the report, which is written to a
local file instead.
local file instead. The one exception is its line on
`User:ParamBot/ReportHistory`, in the bot's own userspace, which says the
run was aborted, when the Run page was changed and by whom. A run that the
Run page stops before it starts adds no line.
- **Large runs are flagged.** There's no limit on edits per run, but a run of
more than 500 edits (`large_run`) gets a note on the report, so a rule that
catches more than it should is noticed. `max_edits`, or `--max-edits N`,
Expand Down Expand Up @@ -361,7 +373,7 @@ Options for `run`:
| `--template NAME` | all | Only use this template's rules. Can be repeated. |
| `--page TITLE` | | Only check this page, skipping the categories. Can be repeated. |
| `--any-namespace` | off | With `--page`, allow non-articles such as sandboxes. Dry runs only. |
| `--report-page`, `--run-page` | `[pages] report`, `[pages] run` | Pages to use instead. |
| `--report-page`, `--run-page`, `--history-page` | `[pages] report`, `[pages] run`, `[pages] history` | Pages to use instead. |
| `--out-dir DIR` | `[output] dir` | Where dry runs, and live runs that can't save the report, write their files. |

Without `--dry-run`, `--report-only` or `--live`, a run does what `mode` in
Expand Down Expand Up @@ -391,7 +403,7 @@ wiki is the English Wikipedia unless `--lang` or `--family` says otherwise.
| Setting | Default | Meaning |
|---|---|---|
| `mode` | `"dry-run"` | What a plain `parambot run` does: `"dry-run"`, `"report-only"` or `"live"`. |
| `[pages]` `rules`, `report`, `run`, `instructions`, `faq`, `header`, `link_rule` | `User:<bot>/Rules`, `/Report` and so on; `instructions` is the rules page's `/Instructions` | The bot's pages. The report page can't be one of the others. |
| `[pages]` `rules`, `report`, `run`, `history`, `instructions`, `faq`, `header`, `link_rule` | `User:<bot>/Rules`, `/Report`, `/ReportHistory` and so on; `instructions` is the rules page's `/Instructions` | The bot's pages. The report page can't be one of the others. The history page must be a page of its own under `User:<bot>/`. |
| `[limits]` `cooldown_days` | `30` | Don't edit a page the bot edited this recently. `0` turns it off. |
| `[limits]` `max_hours` | `20` | Stop starting new work after this many hours, so a run is done before the next starts. The Toolforge job overrides it with `--max-hours 5`. `0` means no limit. |
| `[limits]` `max_edits` | `0` | Stop after this many edits. `0` means no limit. |
Expand Down Expand Up @@ -485,7 +497,8 @@ job then does what the settings say.)
A run goes `cli` → `bot`, which checks the bot's pages (`botpages`), finds
and reads the rules pages (`rulespages`, `rules`), checks the rules against
the templates (`prepare`), then applies the active ones to each article
(`fixer`) and writes the report (`report`). Only `wiki` talks to the wiki.
(`fixer`) and writes the report (`report`), and a line for the run on the
report history (`history`). Only `wiki` talks to the wiki.

| Path | Contents |
|---|---|
Expand All @@ -502,6 +515,7 @@ the templates (`prepare`), then applies the active ones to each article
| `parambot/templatescan.py` | Reading a template's own parameter checks, and wrapper templates; `scaffold`. |
| `parambot/luapattern.py` | Lua patterns, as used in templates, translated to Python regexes. |
| `parambot/report.py` | The report page. |
| `parambot/history.py` | The report history page: a line for each run. |
| `parambot/messages.py` | Everything the bot says on the report, in edit summaries and when it stops. |
| `parambot/wiki.py` | Everything the bot asks of the wiki, through Pywikibot. |
| `parambot/wikitext.py` | Small wikitext helpers. |
Expand Down
4 changes: 4 additions & 0 deletions deploy/parambot.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,10 @@
# if it's a subpage of User:<bot>.
# report = "User:ParamBot/Report"
# run = "User:ParamBot/Run"
# Live and report-only runs add a line here for each run, newest first: when
# it ran, what it did, and how it ended, including when the Run page stopped
# it. It must be a subpage of User:<bot>; the bot creates it if need be.
# history = "User:ParamBot/ReportHistory"
# The default is the rules page's /Instructions subpage.
# instructions = "User:ParamBot/Rules/Instructions"
# Every edit summary links to the FAQ.
Expand Down
9 changes: 9 additions & 0 deletions docs/documentation.mediawiki
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,9 @@
! Report
| [[User:ParamBot/Report]]
|-
! Report history
| [[User:ParamBot/ReportHistory]]
|-
! Emergency stop
| [[User:ParamBot/Run]]: change it to <code>no</code>
|-
Expand Down Expand Up @@ -132,6 +135,7 @@ Four times a day, ParamBot:
# '''Looks at those categories''', 50 at a time, and skips the empty ones.
# '''Fixes each article''' in the categories that have pages. Before each edit, it checks [[User:ParamBot/Run]] again.
# '''Writes the report''' to [[User:ParamBot/Report]].
# '''Adds a line for the run''' to the top of [[User:ParamBot/ReportHistory]]: when it ran, what it did, and how it ended.

It stops early if [[User:ParamBot/Run]] stops saying <code>yes</code>, if five articles in a row fail with errors, or as soon as an edit fails in a way that every other edit would too, such as when the bot is blocked. There's no limit on how many edits a run makes, but a run with more than 500 gets a note on the report, so that a rule catching more than it should is noticed. A run stops after 5 hours, so it's always finished before the next run starts, 6 hours later; whatever is left is done then. During a trial approved at [[WP:BRFA|Bots/Requests for approval]], it counts its edits across runs, stops at the number approved, and shows the count on [[User:ParamBot/Report]]. Each trial edit's summary starts with "BRFA trial", linked to the request.

Expand Down Expand Up @@ -194,6 +198,9 @@ Until then, the report notes that the page has changed, with a link to the chang
* <code>merge</code> is only used for lists, never for dates, numbers, coordinates or map names
* the report shows no problems for the template, which is easiest to check by approving the new revision under Inactive first

== The report history ==
[[User:ParamBot/ReportHistory]] has a line for every run, newest first, except runs that didn't start because [[User:ParamBot/Run]] was off: when it started and ended, in UTC, how long it took, whether it was live, a BRFA trial or reporting only, how many categories had pages, and how many pages it checked, edited and left for review. The last column says how the run ended: finished; finished early, and why; stopped by an error; or aborted because [[User:ParamBot/Run]] was changed, saying when and by whom. It links to the report the run saved. A run aborted by the Run page saves nothing else, but still adds its line here. The bot keeps the newest 200 lines; the text above the table can be edited.

== The report ==
[[User:ParamBot/Report]] is rewritten on every run. Its "Last run" line says when the run started and ended, in UTC, how long it took, and how many rules pages and rules it read, so the page's history is a log of the runs. Wherever it names a rules page, a template or a diff, it links to it. Its sections:

Expand Down Expand Up @@ -260,6 +267,8 @@ Until then, the report notes that the page has changed, with a link to the chang
|-
| [[User:ParamBot/Report]] || What the bot couldn't do, rewritten each run || Must stay editable by the bot
|-
| [[User:ParamBot/ReportHistory]] || A line for each run, added by the bot || Must stay editable by the bot
|-
| [[User:ParamBot/Run]] || The emergency stop: <code>yes</code> to run, <code>report</code> to update only the report, anything else to stop || '''None''', so anyone can stop the bot
|-
| [[User talk:ParamBot]] || Questions and problems || —
Expand Down
9 changes: 7 additions & 2 deletions docs/operators.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ is your Toolforge shell name.
|---|---|
| [User:ParamBot/Run](https://en.wikipedia.org/wiki/User:ParamBot/Run) | The off switch: `yes` to run, `report` to update only the report, anything else to stop. |
| [User:ParamBot/Report](https://en.wikipedia.org/wiki/User:ParamBot/Report) | What the last run found: pages needing review, pages it skipped, and problems with the rules. |
| [User:ParamBot/ReportHistory](https://en.wikipedia.org/wiki/User:ParamBot/ReportHistory) | A line for every live or report-only run, newest first: when it ran, what it did, and how it ended, including runs aborted by the Run page. |
| [User:ParamBot/Rules](https://en.wikipedia.org/wiki/User:ParamBot/Rules) | The approved rules pages, with the revision of each to use. Template-editor protected. |
| [Special:Contributions/ParamBot](https://en.wikipedia.org/wiki/Special:Contributions/ParamBot) | Its edits. |
| [The BRFA](https://en.wikipedia.org/wiki/Wikipedia:Bots/Requests_for_approval/ParamBot) | The approval request. |
Expand Down Expand Up @@ -64,7 +65,10 @@ Each run:
5. saves User:ParamBot/Report, every run. Its first line says when the run
started and ended and how long it took, and its last line names the
commit, such as `<!-- ParamBot 3457b05 -->`. So the report's history is a
log of the runs.
log of the runs;
6. adds a line to the top of User:ParamBot/ReportHistory, however the run
ended: finished, finished early (and why), stopped by an error, or aborted
because someone changed User:ParamBot/Run (with when, and by whom).

A run stops starting new work after 5 hours (the job's `--max-hours 5`), so
it can't still be going when the next one starts, 6 hours later. If you change
Expand Down Expand Up @@ -102,7 +106,8 @@ tail -n 40 ~/parambot.err # the log of the latest run
tail -n 3 ~/parambot.out # one line per run: "Last run: ... 3 edits. Rules: ..."
```

Or look at User:ParamBot/Report and its history.
Or look at User:ParamBot/ReportHistory, a line per run, and
User:ParamBot/Report.

### What would it have edited?

Expand Down
Loading
Loading