livery.workshop._issue_tasks¶
livery.workshop._issue_tasks ¶
The issue family: the shared work pool and its lifecycle.
issue.create, issue.list, and issue.search are the pool's
reads and the one write that files work. The top-level start
lives here too, since most work starts from an issue: it picks an
issue up (assign within the workspace's limit, branch from a fetched
base, open the work in a linked worktree by default), files one from
a quoted title, or starts a plain branch that belongs to no issue.
issue.stop is start's inverse for an issue: unassign, clean up
the local state, and leave the remote branch as the pool's copy.
issue.close closes the issue itself, removes the branch it was
worked on unless an open pull request comes from that branch, and
records where the work got to.
One destruction rule holds everywhere: work that exists nowhere else
is never destroyed without --discard, and the refusal's prose
names the situation it found.
Functions:
| Name | Description |
|---|---|
assignee_limit |
The workspace's assignee limit; policy, not a forge fact. |
parse_ref |
token as |
branch_name |
|
worktree_home |
Where this repository's issue worktrees live under the runner's home. |
worktree_path |
Where the issue's worktree lives: under the runner's home. |
issue_default |
List the open issues (the bare |
issue_list |
The open issues: number, title, who is on them. |
issue_show |
One issue in full: title, state, who is on it, the body, and its thread. |
issue_search |
The open issues whose title or body contains text. |
issue_create |
File a new issue; |
issue_update |
Rewrite an issue's title, body, or both. |
issue_comment |
Add to an issue's thread, leaving its body alone. |
start |
Start work: an issue by number, a title that files one, or a plain branch. |
fetch_base |
Fetch origin's heads and the state store in one round trip; print its lines. |
start_here |
Start branch in this checkout from |
issue_stop |
Stop working on an issue: unassign, clean up the local state. |
issue_close |
Close the issue itself, and remove the branch it was worked on. |
issue_reopen |
Reopen a closed issue and put yourself on it, as start does. |
Attributes:
| Name | Type | Description |
|---|---|---|
issue |
|
assignee_limit ¶
The workspace's assignee limit; policy, not a forge fact.
[issues] assignees in the root workshop.toml, default 1 so
a free GitLab needs nothing. Enforced by the workshop on every
forge, including ones whose native limit is higher; whether the
forge itself can honour it is configure's check.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
parse_ref ¶
token as (number, "") or (0, title).
A token livery.workshop._submit.parse_number reads as a
number, # or not, is one; anything else is a title to file
first. The # matters here: read as a title, #123 would
file a junk issue named with the hash.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
branch_name ¶
worktree_home ¶
Where this repository's issue worktrees live under the runner's home.
The folder is named after the repository's main checkout, which git reports from any of its worktrees, so work started inside a worktree lands beside the rest. A directory that is no checkout is named by itself.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
worktree_path ¶
Where the issue's worktree lives: under the runner's home.
Outside every repository, so repo tooling never walks into a worktree, and under a per-user home so a worktree's venv hardlinks from the same filesystem's cache. The home is the runner's own data directory, asked of footman: a footman plugin owns no home of its own.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
issue_default ¶
issue_list ¶
The open issues: number, title, who is on them.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
issue_show ¶
One issue in full: title, state, who is on it, the body, and its thread.
The body is the work order and the thread its continuation, so both print verbatim. The pull request on the issue's branch is named when one is open, since that is where the work stands. The branch is looked up among the local branches and the remote-tracking refs, so the verb asks no remote of git; a lookup git cannot answer is named in one line, and the body and the thread still print.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
issue_search ¶
The open issues whose title or body contains text.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
issue_create ¶
issue_create(title: Arg[str] = '', type: Annotated[str, doc('kind label: feat, fix, chore, docs, refactor')] = 'feat', body: Annotated[str, doc('the issue body, readable by an outsider')] = '') -> None
File a new issue; start with a title files and starts.
The kind label is best-effort: a forge or token that refuses
labels costs the label, never the issue. Every filed issue
should carry a body an outsider can read; correct one later
with issue.update.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
issue_update ¶
issue_update(number: Arg[int] = 0, title: Annotated[str, doc('the corrected title (empty keeps it)')] = '', body: Annotated[str, doc('the corrected body (empty keeps it)')] = '') -> None
Rewrite an issue's title, body, or both.
Only the provided fields change; clearing a text to empty is not part of the contract. The issue is read first, so a wrong number refuses by name instead of writing nowhere.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
issue_comment ¶
issue_comment(number: Arg[int] = 0, body: Annotated[str, doc("what to add to the issue's thread")] = '') -> None
Add to an issue's thread, leaving its body alone.
The body is the work order and the thread its continuation, so a ruling, a measurement or a change of direction goes here rather than into a rewrite of the body, which would replace the specification a reader opens the issue for. The issue is read first, so a wrong number refuses by name instead of writing nowhere.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
start ¶
start(ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = '', type: Annotated[str, doc('kind override: feat, fix, chore, docs, refactor')] = '', from_: Annotated[str, doc('start on this pushed, unmerged branch instead of main; submit targets it')] = '', body: Annotated[str, doc('the issue body when the title form files one')] = '', wip: Annotated[bool, doc('park the dirty tree as a commit and reuse this checkout')] = False, worktree: Annotated[bool, doc('open the work in a linked worktree')] = True, agent: Annotated[str, doc('hand the work to a coding agent (implies a worktree)')] = '', prompt: Annotated[str, doc("an initial prompt appended to the agent's briefing")] = '', open: Annotated[str, doc('how to open a worktree: shell, code, or none')] = '') -> None
Start work: an issue by number, a title that files one, or a plain branch.
REF is an issue number (a leading # is accepted), a quoted
title, which files the issue first, or <kind>/<slug> (docs/
the-plan) for a branch that belongs to no issue: a note, a small
fix. An issue is assigned, and assignment is documentation: at the
workspace's assignee limit, or when the forge refuses the write,
the start proceeds with a warning that others will not see you on
the issue. An issue's branch is <kind>/<number>-<slug> and
fm submit closes the issue on merge; a plain branch is named
as given and closes nothing. Every branch starts from a fetched
origin/main, so a stale base is impossible; --from=<branch>
starts on a pushed, unmerged parent instead and records the parent
with the commit the branch starts from. fm submit targets the
parent until it has merged, and fm sync and fm submit move
the branch's own commits when the parent moves or merges. A worktree under
the runner's home is the default, entered in a shell when a
person is at the terminal (--open=code opens the editor
instead, --open=none prints the path); --no-worktree
reuses this checkout, where a dirty tree refuses naming --wip
(park the tree as a commit; squash-only merging evaporates it) as
the escape. --agent launches the named agent in the worktree
with a minimal briefing; the worktree's own instructions are the
real ones. Re-running on started work re-enters it, in whichever
tree holds the branch. A local branch no tree holds is re-entered
on its own tip, unless its pull request merged and took that tip:
the branch is finished work, so it goes and the start begins fresh.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 | |
fetch_base ¶
fetch_base(root: Path) -> None
Fetch origin's heads and the state store in one round trip; print its lines.
What a start does before it cuts a branch: the base is origin's and the store's row series are what the branch's first gate reads, the shape a sync's own fetch has.
Raises:
| Type | Description |
|---|---|
Failed
|
when origin could not be fetched, in git's words. |
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
start_here ¶
start_here(root: Path, repo: Repository, branch: str, *, base: str = 'main', parent: str = '', started: str = '') -> None
Start branch in this checkout from origin/<base>, or re-enter it.
The in-place half of start, which the balancer's submit calls
too (livery.workshop._balance.submit). A local branch that is
not finished work is switched to as it stands; one whose pull
request merged goes, and the start begins fresh. origin/<base>
is read as the last fetch left it, so fetch_base comes first.
The working tree is the caller's to check: a dirty one carries
its changes onto the branch. parent records the branch fm
submit targets until it merges; started is how the branch is
announced, its name when empty.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
issue_stop ¶
issue_stop(ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = '', discard: Annotated[bool, doc('destroy work that exists nowhere else')] = False) -> None
Stop working on an issue: unassign, clean up the local state.
The remote branch is never touched; while the issue is open it
stays the pool's copy. Work that exists nowhere else is never
destroyed without --discard, and the refusal names what it
found: a delta the remote is missing, a remote gone while the
issue is open (exceptional), or an issue already closed.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 | |
issue_close ¶
issue_close(ref: Annotated[Arg[str], ask(), suggest(_open_numbers, strict=False)] = '', reason: Annotated[str, doc('why: done, wontfix, duplicate, stale, ...')] = '', message: Annotated[str, doc('free-text detail for the close comment')] = '', keep_branch: Annotated[bool, doc('retain the local and remote branch')] = False, discard: Annotated[bool, doc('destroy work that exists nowhere else')] = False) -> None
Close the issue itself, and remove the branch it was worked on.
An open pull request from the issue's branch keeps the branch and
its worktree: deleting the head branch makes the forge close the
pull request unmerged, and the branch may carry work for another
issue. The close then ends the issue alone and names the pull
request, to be merged or closed first. A forge that cannot say
whether such a pull request is open keeps them too, and the line
names the forge's error. A pull request that already merged means
the work landed, the supplied reason no longer applies, and the
close becomes cleanup: "issue already resolved". Otherwise the
worktree, the local branch, and the remote branch are removed by
default, with the removed head sha recorded in the close comment;
--keep-branch retains them.
Source code in packages/workshop/src/livery/workshop/_issue_tasks.py
825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 | |
issue_reopen ¶
Reopen a closed issue and put yourself on it, as start does.
For an issue a merge closed before its work was done (a branch that carried a plan or a pinning test under the issue's number). Reopening an open issue is a no-op, and the assignment follows start's rules: the workspace's limit and a refused write warn and go on.