Obligations

An obligation is a command that must pass before the registrar accepts satisfaction. An obligation is the check that protects the rest of the project.

obligations:
  - { on: satisfaction, require: { run: "pytest -x -q", exit: 0 } }

The obligations field is optional.

The fields

Field	Value
on	satisfaction. This is the only value now.
require.run	The command.
require.exit	The exit code that the command must give.

Obligations and satisfaction clauses

The two look similar and answer different questions.

Clause	Question
Satisfaction	Is the work complete?
Obligation	Did the work break something else?

Take the bug-fixer example. The satisfaction clause runs the one test that must pass. The obligation runs the full suite:

obligations:
  - { on: satisfaction, require: { run: "pytest -x -q", exit: 0 } }

satisfaction:
  all:
    - { layer: letter, run: "pytest {failing_test} -x -q", exit: 0 }

The named test proves the fix. The full suite proves that the fix broke nothing. If the full suite fails, the registrar does not accept satisfaction, and the run continues.

Write the obligation that your project already has

The best obligation is the command that your continuous integration already runs. If a change must pass make check before a person can merge it, then an agent must pass make check too.

obligations:
  - { on: satisfaction, require: { run: "make check", exit: 0 } }