Changes between Initial Version and Version 1 of patchbot


Ignore:
Timestamp:
Apr 18, 2022, 3:07:09 AM (6 months ago)
Author:
Matthias Köppe
Comment:

Move here from https://wiki.sagemath.org/patchbot

Legend:

Unmodified
Added
Removed
Modified
  • patchbot

    v1 v1  
     1== The Sage Patchbot ==
     2
     3The patchbot pulls and applies git branches from Trac and can be found at https://patchbot.sagemath.org or from links on the individual Trac tickets (round icons at top right).
     4
     5You can help by running your own patchbot. See below for instructions about installation and usage.
     6
     7See a list of some patchbot names and their owners at [[patchbot/owners]].
     8
     9This is still very much a work in progress. The latest version of the code lives at http://github.com/sagemath/sage-patchbot.
     10
     11== Lists of reports ==
     12
     13You can see the status of several tickets at the same time (replace xxxx by your user name):
     14
     15For the tickets you participated in, see https://patchbot.sagemath.org/ticket/?base=develop&participant=xxxx
     16
     17For the tickets you authored, see https://patchbot.sagemath.org/ticket/?base=develop&author=xxxx
     18
     19=== Ticket Status ===
     20
     21The color of the report page icon indicates the status of the ticket. See the report page itself for more details. The possible statuses are:
     22
     23[[Image(https://patchbot.sagemath.org/svg/New, width=48)]] '''New'''
     24
     25[[Image(https://patchbot.sagemath.org/svg/Pending, width=48)]] '''Pending''' A patchbot is currently running on this ticket. The patchbot may have stopped if the ticket was deemed unsafe.
     26
     27[[Image(https://patchbot.sagemath.org/svg/TestsPassed, width=48)]] '''!TestsPassed''' Everything is okay, as far as a patchbot can tell.
     28
     29[[Image(https://patchbot.sagemath.org/svg/TestsPassedOnRetry, width=48)]] '''!TestsPassedOnRetry''' Everything is okay, but only after several tentatives.
     30
     31[[Image(https://patchbot.sagemath.org/svg/ApplyFailed, width=48)]] '''!ApplyFailed''' The branch could not be applied. This can be caused by conflicts with other branches or dependencies. Try rebase your branch on the latest develop branch.
     32
     33[[Image(https://patchbot.sagemath.org/svg/BuildFailed, width=48)]] '''!BuildFailed''' The branch can be applied, but sage failed to build, due to errors in the code. Check the code.
     34
     35[[Image(https://patchbot.sagemath.org/svg/TestsFailed, width=48)]] '''!TestsFailed''' One or more tests did not succeed.
     36
     37[[Image(https://patchbot.sagemath.org/svg/PluginFailed, width=48)]] '''!PluginFailed''' Tests have been successfully done, but plugins have found some problems.
     38
     39[[Image(https://patchbot.sagemath.org/svg/PluginOnlyFailed, width=48)]] '''!PluginOnlyFailed''' Plugin have found some problems. Tests have not been made.
     40
     41[[Image(https://patchbot.sagemath.org/svg/PluginOnly, width=48)]] '''!PluginOnly''' Plugins have found no problem. Tests have not been made.
     42
     43[[Image(https://patchbot.sagemath.org/svg/NoPatch, width=48)]] '''!NoPatch''' No branch has been uploaded to Trac so far. The patchbot has nothing to do.
     44
     45[[Image(https://patchbot.sagemath.org/svg/Spkg, width=48)]] '''Spkg''' This is related to an spkg. The patchbot will only check the spkg installation.
     46
     47=== Hints and tricks ===
     48
     49 * To rerun tests (even though the branch was not modified) add the kick parameter, e.g., http://patchbot.sagemath.org/ticket/12345/?kick
     50== Installing the patchbot ==
     51
     52It is safer to run the patchbot in an unused sage install.
     53
     54||<#FFFF66>① Install the patchbot using '''pip3 install --user git+https://github.com/sagemath/sage-patchbot.git'''||
     55
     56or using PyPI:
     57
     58||<#FFFF66>① Install the patchbot using '''pip3 install --user sage-patchbot'''||
     59
     60
     61Dependencies: shell commands '''git'''; '''tar'''; '''wget'''
     62
     63'''pyflakes''' and '''pycodestyle''' will be installed by pip if not already installed.
     64
     65||<#98FF98> Please set the --owner option if you run a patchbot. It is useful to know whom to contact.||
     66
     67You can instead register [[patchbot/owners|here]].
     68
     69== Installing optional packages ==
     70
     71You are allowed and in fact even encouraged to install optional packages in sage before running the patchbot. When doing so, please keep in mind that certain optional packages require things outside of sage to be installed.
     72The following list of commands is handy if one wants to install ''all'' optional packages.
     73
     74{{{
     75sage -pip install service_identity
     76apt-get install graphviz pandoc build-essential libxml2 libxml2-dev
     77}}}
     78
     79== Running the patchbot ==
     80
     81Before running the patchbot make sure that the following two commands produce no errors when executed in the root of the sage installation you want to run the patchbot with.
     82
     83{{{
     84    make
     85    ./sage -t --all --long
     86}}}
     87
     88||<#FFFF66>② Run the patchbot using '''python3 -m sage_patchbot.patchbot --sage-root HERE_PATH --owner HERE_NAME'''||
     89
     90The patchbot should be run with '''pip3''' and '''python3'''. The version of Python must be at least 3.7.
     91
     92The '''--sage-root''' parameter is required.
     93
     94Your patchbot will run forever, as long as it finds a ticket to work on.
     95
     96You can let the patchbot choose the tickets it will run on.
     97
     98You can run a specific ticket by using '''--ticket N''' where N is a ticket number such as 12345 (or a sequence such as 12345,23456)
     99
     100Several other options are available, see '''--help'''
     101
     102'''--skip-base''' will skip the check that the base sage installation is sane. Please do not use when running on many tickets.
     103
     104'''--plugin-only''' will only build (sage and the doc) and run the plugins but not the tests (much quicker but less useful).
     105
     106'''--safe-only''' will only test branches that only change files inside the directory "src/sage" (this is the case by default).
     107
     108'''--skip-doc-clean''' the "make doc-clean" is not run during the patchbot initialization. Useful if your machine does not have enough ram to build the documentation in a single round.
     109
     110If the patchbot process receives the signal SIGUSR1 (using {{{kill -s SIGUSR1 pid}}}), it will gracefully stop after finishing its job on the ticket it is currently working on.
     111
     112== Configuration ==
     113
     114By default, the patchbot should run without needing to tune its configuration. You can use a specific configuration file in the json format and run the patchbot with the option
     115{{{
     116--config fullpath/config_file.json
     117}}}
     118The json format mostly looks like a python dictionary. Here is an example of a valid configuration file
     119{{{
     120    {"bonus": {"niceguy": 200, "needs_work": -20},
     121     "use_ccache": false,
     122     "safe_only": true,
     123     "skip_base": true,
     124     "time_of_day": "22-7",
     125     "parallelism": 8
     126    }
     127}}}
     128Note that the booleans must be written with no capital first letter.
     129
     130The config will be read again between every run, hence it allows live configuration of the patchbot.
     131
     132The list of configurable entities are:
     133
     134|| option                    || type            || default       || description                                                                       ||
     135|| ''time_of_day''           || string          || "0-0"         || (example "0-0" or "22-7") an interval of time during which the patchbot is active ||
     136|| ''bonus''                 || dictionary      || ''see below'' || some bonus to influence the order in which tickets are tested (see below)         ||
     137|| ''safe_only''             || boolean         || true          || whether to only test "safe" tickets modifying only src/sage or src/doc            ||
     138|| ''skip_base''             || boolean         || false         || whether to run testlong on the base before testing tickets                        ||
     139|| ''parallelism''           || integer         || 3             || the number of threads to execute when compiling or testing                         ||
     140|| ''idle''                  || integer         || 300           || seconds to wait when network is not working or there are no tickets available     ||
     141|| ''timeout''               || integer         || 10800         ||                                                                                   ||
     142|| ''base_branch''           || string          || develop       || the name of the git branch to synchronized with the develop branch on trac        ||
     143|| ''sage_root''           || string          ||        || the path to the directory containing the sage installation ||
     144|| ''plugins''               || list of strings || ''see below'' || the plugins to use                                                                ||
     145|| ''test_options''               || string         || "" || anything that can be passed to sage -t --optional, for example "sage,external" or "sage,internet"                                            ||
     146
     147=== bonus ===
     148
     149There are two kinds of bonus, the one related to tickets:
     150
     151 * ''logins'' (counted x2 if author and x1 if participant)
     152 * ''component'' (e.g. "linear algebra", "combinatorics", ...)
     153 * ''status'' (e.g. "needs_review", "positive_review", ...)
     154 * ''priority'' (e.g "blocker", "critical", ...)
     155
     156and the one related to other bot reports:
     157
     158 * ''behind'': weight the number of commits behind master
     159          (and count for -1 if the commit is not locally available)
     160 * ''applies'': whether previous bots succeeded when merging the branch with the current beta
     161 * ''unique'' : give less chance for already seen tickets
     162
     163The defaults are
     164{{{
     165 "bonus": {
     166     "blocker"        : 100,
     167     "critical"       : 60,
     168     "major"          : 10,
     169     "minor"          : 0,
     170     "needs_review"   : 1000,
     171     "positive_review": 500,
     172     "needs_info"     : 0,
     173     "needs_work"     : 0,
     174     "unique"         : 40,
     175     "applies"        : 20,
     176     "behind"         : 1
     177    }
     178}}}
     179But you could add
     180{{{
     181 "bonus": {
     182     "vbraun": 10,
     183     "inconito": -5,
     184     "linear programming": 200,
     185     "finance": -200,
     186     "14382": 100,
     187     "15777": 100
     188     }
     189}}}
     190
     191== Looking at patchbot activities ==
     192
     193Remotely, you can have a look at the last tickets tested by patchbots at https://patchbot.sagemath.org/ and the tests without tickets applied can be found at http://patchbot.sagemath.org/ticket/0/.
     194
     195On your machine, the patchbot writes a summary of its activities in $SAGE_ROOT/logs/patchbot/history.txt
     196
     197== using an ipython session ==
     198
     199You can try the patchbot inside a ipython session, as follows.
     200
     201First, in the sage directory, create a branch "patchbot/base" by
     202{{{
     203git checkout develop -b patchbot/base
     204}}}
     205then
     206{{{
     207cd sage-patchbot/
     208}}}
     209launch ipython and
     210{{{
     211from sage_patchbot.patchbot import Patchbot
     212
     213opt = {'sage_root': '/home/platon/sage/', 'owner': 'Sophocle'}
     214
     215P = Patchbot(opt)
     216
     217P.test_a_ticket(14974)   # just test one ticket and stop
     218
     219P.test_some_tickets([14974, 19876, 20202])  # test several tickets in the given order
     220}}}
     221
     222The argument dictionary must contain at least:
     223{{{
     224{'sage_root': path to the sage local repository}
     225}}}
     226
     227== Example Configuration and Run-Scripts ==
     228
     229Installation via
     230{{{
     231pip3 install --user git+https://github.com/sagemath/sage-patchbot.git
     232}}}
     233or
     234{{{
     235pip3 install --user sage-patchbot
     236}}}
     237
     238Configuration {{{config.json}}}:
     239{{{
     240{
     241    "bonus": {"me": 100},
     242    "parallelism": 2,
     243    "sage_root": "/local/sage-patchbot/sage",
     244    "owner": "This Is Me <this.is@me.org>"
     245}
     246}}}
     247
     248Script {{{bin/run-patchbot}}}:
     249{{{
     250#!/bin/bash
     251LANG=C python3 -m sage_patchbot.patchbot --config=/local/sage-patchbot/config.json
     252}}}
     253
     254== Running the patchbot on GitHub Actions ==
     255
     256
     257Go to https://github.com/sagemath/sage-patchbot, use the Fork button to create a fork in your account.
     258
     259Go to the Actions tab,  select "Run patchbot". Push "Run workflow".
     260
     261Instead of the default platform, `ubuntu-focal-standard`, you can select any platform for which we have prebuilt images, see https://github.com/orgs/sagemath/packages?tab=packages&q=with-targets-optional
     262
     263It will run for 6 hours, then exit. You can run multiple workflows simultaneously.
     264
     265See also [[https://trac.sagemath.org/ticket/33253|#33253]].