Resume a chunk that awaits a person's merge once its pull request no longer merges into its base
CI / tests (pull_request) Successful in 3m29s
CI / tests (pull_request) Successful in 3m29s
This commit is contained in:
@@ -119,7 +119,7 @@ A legacy project with no container setup sets `tooling-on-host = true`, so the l
|
||||
|
||||
A project whose pull requests need a human's approval sets `wait-for-approval = true` in its config. `chunk-pr merge` then waits, once the checks have passed, until GitHub reports the pull request approved as its branch protection requires, and merges it. It refuses on Gitea, where a reviewer requested changes and where the protection requires no review. While it waits, other chunks merge. It stops where a reviewer's comment waits for an answer, on an approved pull request too; answer it and run it again. It gives up after 90 minutes without an approval; run it again once the pull request is approved. Left out, the setting is false.
|
||||
|
||||
A project whose team merges its pull requests itself sets `merge = "human"`. `chunk-pr merge` then brings the branch level with origin's default branch, finishes the chunk's plan items, waits for the checks and marks the pull request ready, but leaves the merge to a person. A plan or changelog kept in the checkout is finished on the branch, so it lands with that merge; one kept in Jira, or in the config's folder, is finished at once. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. Left out, the setting is `"chunk"`: the chunk merges.
|
||||
A project whose team merges its pull requests itself sets `merge = "human"`. `chunk-pr merge` then brings the branch level with origin's default branch, finishes the chunk's plan items, waits for the checks and marks the pull request ready, but leaves the merge to a person. A plan or changelog kept in the checkout is finished on the branch, so it lands with that merge; one kept in Jira, or in the config's folder, is finished at once. A do-epic chunk parks until the pull request is merged, and its window's name says `awaits your merge`. Where the pull request meanwhile conflicts with the default branch, or is behind it where GitHub's branch protection requires an up-to-date branch, the chunk resumes and brings the branch level again. Left out, the setting is `"chunk"`: the chunk merges.
|
||||
|
||||
For a client's project, use one sandbox VM per client, so that one client's code, transcripts and credentials never share a machine with another's. What the client's repo should not hold lives in the config's folder, at paths written as `folder:<path>`, as `project-config --help` shows: the plan, the working rules in an `AGENTS.md` I write for the agents, the records, and the goals and audience, as `goals-and-audience = "folder:goals.md"`. Name that file `goals.md`, so the rules for goals and audience load when an agent writes it. A file outside the checkout has no commits in the checkout's history, so four things are not supported for it yet. `score-outcomes` and loop-claude's routing figures count a project's chunks only where `todo.md`, `docs/comprehension-history.md` and `docs/reading-cost.md` are at those paths in the checkout; otherwise each says so, and the loop goes on. For a plan or a comprehension history outside the checkout, `larv-review` says it cannot tell whether a scoring run is owed, and for such a history it cannot find a paired ruling's base. For a plan outside the checkout, chunk-preflight and loop-claude don't see a release whose last item has shipped, and say that its release review and its cut are yours to call. And rule-hook checks a plan outside the checkout on every call, not only when it changed.
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ import dataclasses
|
||||
import typing
|
||||
|
||||
from forge.reviews import ANSWERED, APPROVED, CHANGES_REQUESTED, review_decision, REVIEW_REQUIRED, waiting_threads
|
||||
from forge.pulls import CheckFailed, checks_now, open_pull, Pending, required_checks
|
||||
from forge.pulls import CheckFailed, checks_now, open_pull, Pending, required_checks, unmergeable
|
||||
from failure import Failure
|
||||
from forge.commands import forge_of, Run
|
||||
|
||||
@@ -42,7 +42,7 @@ class Unopened(Open):
|
||||
def gate(branch: str, checkout: str, at: typing.Callable[[str], Run], by_human: bool) -> Gate | Open | Failure:
|
||||
"""What the chunk on branch waits on, in a worktree of checkout; at gives the runner of commands in a folder, and by_human says the project's config leaves the merge to a person (`merge = "human"`). A Failure where git or the forge cannot be read, which doesn't say anything about the gate.
|
||||
|
||||
A draft never waits on a gate: its worker still works on it. On Gitea only the checks are a gate, since chunk-pr reads approvals on GitHub only (`chunk_pr.approval.awaited`). Changes a reviewer requested are news until the worker answered them (`forge.reviews.answered`); from then on the pull request awaits a new review. Where a person merges, a pull request with nothing else to wait on awaits that merge, and the chunk has news again once the pull request is no longer open.
|
||||
A draft never waits on a gate: its worker still works on it. On Gitea only the checks are a gate, since chunk-pr reads approvals on GitHub only (`chunk_pr.approval.awaited`). Changes a reviewer requested are news until the worker answered them (`forge.reviews.answered`); from then on the pull request awaits a new review. Where a person merges, a pull request with nothing else to wait on awaits that merge. The chunk has news again once the pull request is no longer open, or no longer merges into its base as it stands (`forge.pulls.unmergeable`), so the worker levels it for that person.
|
||||
"""
|
||||
worktree = worktree_of(branch, at(checkout))
|
||||
if not isinstance(worktree, str):
|
||||
@@ -77,9 +77,13 @@ def gate(branch: str, checkout: str, at: typing.Callable[[str], Run], by_human:
|
||||
return Open(f"a reviewer's comment on pull request #{pull} waits for an answer, in {', '.join(waiting)}")
|
||||
if decision in (ANSWERED, REVIEW_REQUIRED):
|
||||
return Gate(worktree, pull, NEW_REVIEW if decision == ANSWERED else APPROVAL)
|
||||
if by_human:
|
||||
return Gate(worktree, pull, MERGE)
|
||||
return Open(f"pull request #{pull} passed its checks" + (" and is approved" if decision == APPROVED else ""))
|
||||
if not by_human:
|
||||
return Open(f"pull request #{pull} passed its checks" + (" and is approved" if decision == APPROVED else ""))
|
||||
blocked = unmergeable(forge, pull, run)
|
||||
if isinstance(blocked, Failure):
|
||||
return blocked
|
||||
# The same flags, since merge passes over an item an earlier run finished, and finishes one that resolving a conflict brought back.
|
||||
return Open(f"pull request #{pull} {blocked}; run chunk-pr merge again, with the flags it had, to level the branch") if blocked else Gate(worktree, pull, MERGE)
|
||||
|
||||
|
||||
def worktree_of(branch: str, run: Run) -> str | None | Failure:
|
||||
|
||||
@@ -28,7 +28,7 @@ def comment(by: str, at: str) -> dict:
|
||||
class Forge:
|
||||
"""Stands in for git and the forge's CLI in the checkout and the chunk's worktree; `ran` holds each folder a command ran in. Only the CLI of origin's forge answers: `gh` fails on a Gitea origin, and `tea` on a GitHub one."""
|
||||
|
||||
def __init__(self, origin: str = "git@github.com:o/billing.git", pulls: str = f"7\t{HEAD}\tfalse\n", draft: bool = False, decision: str = "REVIEW_REQUIRED", buckets: tuple[str, ...] = ("pass",), threads: tuple[dict, ...] = (), status: str = '{"state": "success", "total_count": 1}', worktrees: str = WORKTREES, fails: str = "", reviews: tuple[dict, ...] = (), comments: tuple[dict, ...] = (), title: str = "Add x") -> None:
|
||||
def __init__(self, origin: str = "git@github.com:o/billing.git", pulls: str = f"7\t{HEAD}\tfalse\n", draft: bool = False, decision: str = "REVIEW_REQUIRED", buckets: tuple[str, ...] = ("pass",), threads: tuple[dict, ...] = (), status: str = '{"state": "success", "total_count": 1}', mergeable: str = "MERGEABLE", merge_state: str = "CLEAN", worktrees: str = WORKTREES, fails: str = "", reviews: tuple[dict, ...] = (), comments: tuple[dict, ...] = (), title: str = "Add x") -> None:
|
||||
self.cli = "gh" if "github.com" in origin else "tea"
|
||||
self.ran: list[str] = []
|
||||
self.commands: list[list[str]] = []
|
||||
@@ -39,11 +39,11 @@ class Forge:
|
||||
"git rev-parse": HEAD + "\n",
|
||||
"git symbolic-ref": "origin/main\n",
|
||||
"gh pr list": pulls,
|
||||
"gh pr view": json.dumps({"isDraft": draft, "reviewDecision": decision, "author": {"login": "worker"}, "reviews": list(reviews), "comments": list(comments)}),
|
||||
"gh pr view": json.dumps({"isDraft": draft, "reviewDecision": decision, "author": {"login": "worker"}, "reviews": list(reviews), "comments": list(comments), "mergeable": mergeable, "mergeStateStatus": merge_state}),
|
||||
"gh pr checks": json.dumps([{"bucket": bucket} for bucket in buckets]),
|
||||
"gh api graphql": json.dumps({"data": {"repository": {"pullRequest": {"author": {"login": "worker"}, "reviewThreads": {"nodes": list(threads)}}}}}),
|
||||
"tea api repos/{owner}/{repo}/pulls?state=open&limit=50": json.dumps([{"number": 7, "merged": False, "head": {"label": "ABC-21", "sha": HEAD, "repo": {"full_name": "o/billing"}}, "base": {"repo": {"full_name": "o/billing"}}}]),
|
||||
"tea api repos/{owner}/{repo}/pulls/7": json.dumps({"number": 7, "title": title}),
|
||||
"tea api repos/{owner}/{repo}/pulls/7": json.dumps({"number": 7, "title": title, "mergeable": mergeable == "MERGEABLE"}),
|
||||
"tea api repos/{owner}/{repo}/branches/main": '{"name": "main"}',
|
||||
"tea api repos/{owner}/{repo}/commits/" + HEAD + "/status": status,
|
||||
}
|
||||
@@ -79,6 +79,26 @@ class GateOfAChunk(unittest.TestCase):
|
||||
self.assertEqual(forge.gate(by_human=True), Gate("/code/billing-ABC-21", "7", MERGE))
|
||||
self.assertEqual(Forge(decision="APPROVED").gate(by_human=False), Open("pull request #7 passed its checks and is approved"))
|
||||
|
||||
def test_where_a_person_merges_a_pull_request_that_no_longer_merges_into_its_base_is_news_to_level_it(self):
|
||||
gitea = "https://gitea.larvit.se/o/billing.git"
|
||||
again = "run chunk-pr merge again, with the flags it had, to level the branch"
|
||||
self.assertEqual(Forge(decision="APPROVED", mergeable="CONFLICTING", merge_state="DIRTY").gate(by_human=True), Open(f"pull request #7 conflicts with its base branch; {again}"))
|
||||
self.assertEqual(Forge(gitea, mergeable="CONFLICTING").gate(by_human=True), Open(f"pull request #7 conflicts with its base branch; {again}"))
|
||||
self.assertEqual(Forge(decision="", merge_state="BEHIND").gate(by_human=True), Open(f"pull request #7 is behind its base branch, whose protection requires it up to date; {again}"))
|
||||
|
||||
def test_where_a_person_merges_a_pull_request_awaits_that_merge_while_github_computes_whether_it_merges(self):
|
||||
self.assertEqual(Forge(decision="APPROVED", mergeable="UNKNOWN", merge_state="UNKNOWN").gate(by_human=True), Gate("/code/billing-ABC-21", "7", MERGE))
|
||||
|
||||
def test_where_a_person_merges_a_mergeability_that_cannot_be_read_is_a_failure(self):
|
||||
forge = Forge("https://gitea.larvit.se/o/billing.git")
|
||||
forge.answers["tea api repos/{owner}/{repo}/pulls/7"] = '{"number": 7, "title": "Add x"}'
|
||||
self.assertEqual(forge.gate(by_human=True), Failure("tea api answered pull request 7 in a shape that can't be read: {'number': 7, 'title': 'Add x'}"))
|
||||
|
||||
def test_where_the_loop_merges_nobody_reads_whether_the_pull_request_merges(self):
|
||||
forge = Forge(decision="APPROVED", mergeable="CONFLICTING")
|
||||
self.assertEqual(forge.gate(), Open("pull request #7 passed its checks and is approved"))
|
||||
self.assertNotIn(["gh", "pr", "view", "7", "--json", "mergeable,mergeStateStatus"], forge.commands)
|
||||
|
||||
def test_where_a_person_merges_every_other_gate_and_all_news_stay_as_they_are(self):
|
||||
same = (Forge(), Forge(buckets=("pending",)), Forge(draft=True), Forge(decision="CHANGES_REQUESTED"), Forge(threads=(thread(False, "reviewer"),)), Forge(buckets=("fail",)), Forge(pulls=""))
|
||||
for forge in same:
|
||||
|
||||
+29
-1
@@ -1,4 +1,4 @@
|
||||
"""Finding a pull request from origin's own branch, and waiting for the checks on its head commit."""
|
||||
"""Finding a pull request from origin's own branch, reading whether it merges into its base, and waiting for the checks on its head commit."""
|
||||
import dataclasses
|
||||
import fnmatch
|
||||
import json
|
||||
@@ -44,6 +44,34 @@ def pull_at(forge: Forge, branch: str, head: str, state: typing.Literal["open",
|
||||
return Failure(f"tea api listed pull requests in a shape that can't be read: {str(pulls)[:200]}")
|
||||
|
||||
|
||||
# Why a pull request doesn't merge into its base as it stands, as the words after "pull request #<N>".
|
||||
CONFLICTS = "conflicts with its base branch"
|
||||
BEHIND = "is behind its base branch, whose protection requires it up to date"
|
||||
|
||||
|
||||
def unmergeable(forge: Forge, number: str, run: Run) -> str | None | Failure:
|
||||
"""Why pull request number doesn't merge into its base as it stands: CONFLICTS or BEHIND. None where it merges, and while GitHub still computes whether it does.
|
||||
|
||||
GitHub reports a pull request as behind only where the base's protection requires an up-to-date branch. Gitea's `mergeable` never tells that case. It is also false for the seconds Gitea checks for conflicts after a push to either branch, which reads as CONFLICTS here.
|
||||
"""
|
||||
if forge == "gh":
|
||||
viewed = run(["gh", "pr", "view", number, "--json", "mergeable,mergeStateStatus"])
|
||||
if isinstance(viewed, Failure):
|
||||
return viewed
|
||||
try:
|
||||
state = json.loads(viewed)
|
||||
return CONFLICTS if state["mergeable"] == "CONFLICTING" else BEHIND if state["mergeStateStatus"] == "BEHIND" else None
|
||||
except (ValueError, KeyError, TypeError):
|
||||
return Failure(f"gh pr view printed no mergeability: {viewed.strip()[:200]}")
|
||||
pull = gitea(run, f"repos/{{owner}}/{{repo}}/pulls/{number}")
|
||||
if isinstance(pull, Failure):
|
||||
return pull
|
||||
try:
|
||||
return CONFLICTS if pull["mergeable"] is False else None
|
||||
except (KeyError, TypeError):
|
||||
return Failure(f"tea api answered pull request {number} in a shape that can't be read: {str(pull)[:200]}")
|
||||
|
||||
|
||||
def required_checks(forge: Forge, base: str, run: Run) -> set[str] | Failure:
|
||||
"""The checks, or glob patterns of checks, that the forge's protection of the branch base requires before a merge. None on GitHub, where gh's watch covers them.
|
||||
|
||||
|
||||
+37
-1
@@ -6,7 +6,7 @@ import unittest
|
||||
|
||||
sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
|
||||
|
||||
from forge.pulls import CheckFailed, checks_now, checks_passed, open_pull, Pending, POLL_SECONDS, required_checks, WAIT_SECONDS
|
||||
from forge.pulls import BEHIND, CheckFailed, checks_now, checks_passed, CONFLICTS, open_pull, Pending, POLL_SECONDS, required_checks, unmergeable, WAIT_SECONDS
|
||||
from failure import Failure
|
||||
from forge.commands import forge_of, gitea, url_beside
|
||||
|
||||
@@ -47,6 +47,42 @@ class OpenPull(unittest.TestCase):
|
||||
self.assertEqual(open_pull("tea", "item-3", "abc", lambda command: LONG).reason, f"tea api listed pull requests in a shape that can't be read: {LONG[:200]}")
|
||||
|
||||
|
||||
class Unmergeable(unittest.TestCase):
|
||||
def gh(self, mergeable: str, state: str) -> str | None | Failure:
|
||||
commands: list[list[str]] = []
|
||||
answer = unmergeable("gh", "7", lambda command: commands.append(command) or f'{{"mergeable": "{mergeable}", "mergeStateStatus": "{state}"}}')
|
||||
self.assertEqual(commands, [["gh", "pr", "view", "7", "--json", "mergeable,mergeStateStatus"]])
|
||||
return answer
|
||||
|
||||
def test_a_github_pull_request_that_conflicts_with_its_base_says_so(self):
|
||||
self.assertEqual(self.gh("CONFLICTING", "DIRTY"), CONFLICTS)
|
||||
|
||||
def test_a_github_pull_request_behind_a_base_that_requires_it_up_to_date_says_so(self):
|
||||
self.assertEqual(self.gh("MERGEABLE", "BEHIND"), BEHIND)
|
||||
|
||||
def test_a_github_pull_request_merges_whatever_else_holds_it_and_while_github_computes(self):
|
||||
for mergeable, state in (("MERGEABLE", "CLEAN"), ("MERGEABLE", "BLOCKED"), ("MERGEABLE", "UNSTABLE"), ("UNKNOWN", "UNKNOWN")):
|
||||
with self.subTest(mergeable=mergeable, state=state):
|
||||
self.assertIsNone(self.gh(mergeable, state))
|
||||
|
||||
def test_a_gitea_pull_request_conflicts_only_where_gitea_says_it_is_not_mergeable(self):
|
||||
commands: list[list[str]] = []
|
||||
self.assertEqual(unmergeable("tea", "7", lambda command: commands.append(command) or '{"number": 7, "mergeable": false}'), CONFLICTS)
|
||||
self.assertEqual(commands, [["tea", "api", "repos/{owner}/{repo}/pulls/7"]])
|
||||
self.assertIsNone(unmergeable("tea", "7", lambda command: '{"number": 7, "mergeable": true}'))
|
||||
|
||||
def test_fails_where_the_forge_cannot_be_read_or_answers_in_another_shape(self):
|
||||
unread = Failure("no network")
|
||||
for forge in ("gh", "tea"):
|
||||
with self.subTest(forge=forge):
|
||||
self.assertIs(unmergeable(forge, "7", lambda command: unread), unread)
|
||||
self.assertEqual(unmergeable("gh", "7", lambda command: LONG).reason, f"gh pr view printed no mergeability: {LONG[:200]}")
|
||||
self.assertEqual(unmergeable("gh", "7", lambda command: "not json").reason, "gh pr view printed no mergeability: not json")
|
||||
self.assertEqual(unmergeable("gh", "7", lambda command: '{"mergeable": "MERGEABLE"}').reason, 'gh pr view printed no mergeability: {"mergeable": "MERGEABLE"}')
|
||||
self.assertEqual(unmergeable("tea", "7", lambda command: LONG).reason, f"tea api answered pull request 7 in a shape that can't be read: {LONG[:200]}")
|
||||
self.assertEqual(unmergeable("tea", "7", lambda command: '{"number": 7}').reason, "tea api answered pull request 7 in a shape that can't be read: {'number': 7}")
|
||||
|
||||
|
||||
def tea(statuses: typing.Iterable[str], branch: str = '{"name": "main"}') -> typing.Callable[[list[str]], str]:
|
||||
"""A tea answering each read of the head's status with the next of statuses, and of branch main with branch."""
|
||||
answers = iter(statuses)
|
||||
|
||||
+1
-1
@@ -153,7 +153,7 @@ Valid while `~/.claude` is a checkout of this repo.
|
||||
- **Releases.** An epic item has no release. It ships into its repo's unreleased work: where the repo publishes something others consume, a bullet under `CHANGELOG.md` → `## Unreleased`, or nothing where the repo's plan is in Jira. The issue is no item of the repo's plan, so the chunk's worker writes the bullet in its branch and runs `chunk-pr merge` without `--finish`.
|
||||
- **Repos.** A repo's name is its main checkout's folder name, and a project config names that checkout. A missing checkout is cloned from the host of the epic's other repos; where unsure, do-epic asks. Unsure means the other repos don't all sit under one host and owner (the same host spelt as https and as ssh counts as two), an origin can't be read or isn't an https, ssh or scp-style address, the folder to clone into holds something else, or the clone fails. A repo no config names is cloned into the clone folder, and the human is asked to write its config. Each chunk uses its repo's model, routing, and language for commits and PRs. Jira text is in the epic's language, or else the machine's default.
|
||||
- **Running.** The epic caps the chunks running at once, and each repo's `parallel-chunks` still applies. do-epic and loop-claude never run chunks in the same repo at once. The cap is a line of the epic's description, `**Max parallel chunks:** 2`, and 1 without it, as `parallel-chunks` is. A repo's `parallel-chunks` counts the chunks of every epic in its checkout. Each window is named for its issue's key, and a tmux window option, `@chunk-root`, names the folder its chunk works in, which is how loop-claude sees do-epic's chunks in a checkout. do-epic and loop-claude each hold the checkout's `starting` lock from checking the checkout's chunks to starting a window there. A chunk without a repo works in `~/.local/state/do-epic/<EPIC-KEY>/`. do-epic archives its cycles under `~/.claude/do-epic-transcripts/`, not in loop-claude's archive, whose readers parse loop-claude's prompts. An open issue runs once a label records its repo; until do-epic picks repos itself, an issue without one waits, and `do-epic <EPIC-KEY>` says so.
|
||||
- **Long gates.** A chunk whose PR waits on a gate, such as a human approval, parks. It keeps its worktree, PR and session, and its state is in a file that survives a reboot. A parked chunk takes no running slot, and the items it blocks wait. do-epic polls the forge and resumes the chunk's session when the gate passes or a reviewer comments. It fixes reasonable feedback, replies to the rest, and changes the setup so review would have caught it. `do-epic <key> --status` and the tmux window names show what each chunk waits on. A gate is a pull request's pending checks or, on GitHub, the approval its branch protection requires; a draft waits on neither, since its worker has yet to mark it ready. On Gitea a draft is a pull request whose title opens with `WIP:` or `[WIP]`, Gitea's default `WORK_IN_PROGRESS_PREFIXES`. Changes a reviewer requested resume the chunk only while that review was made on the pull request's head commit and the pull request's author has not commented or replied after it; once the worker pushed or replied, the chunk parks on a new review, since GitHub keeps the decision until the reviewer reviews again. The chunk's window reads the forge once a minute, which no forge's rate limit notices. A chunk resumes only into a free slot, under the limits a starting chunk meets, and stays parked until then. `do-epic <key>` starts a parked chunk's window again whatever the limits, since the chunk stays parked. do-epic sets `CHUNK_PR_PARKS=1` for each worker, so `chunk-pr merge` fails at once where the pull request awaits an approval, and the worker's run doesn't hold a slot while the pull request waits. In a repo whose config sets `merge = "human"`, the merge itself is a gate: `chunk-pr merge` leaves the pull request ready, the chunk parks on `your merge` once nothing else holds the pull request, and it resumes when the forge no longer reports the pull request open, to clean up and finish. The judge may rule such a chunk finished while its pull request is open, since its worker ends each run there. So do-epic reads a gate it could not read again before it hands the chunk on, and tells the worker once to remove a worktree whose pull request is no longer open.
|
||||
- **Long gates.** A chunk whose PR waits on a gate, such as a human approval, parks. It keeps its worktree, PR and session, and its state is in a file that survives a reboot. A parked chunk takes no running slot, and the items it blocks wait. do-epic polls the forge and resumes the chunk's session when the gate passes or a reviewer comments. It fixes reasonable feedback, replies to the rest, and changes the setup so review would have caught it. `do-epic <key> --status` and the tmux window names show what each chunk waits on. A gate is a pull request's pending checks or, on GitHub, the approval its branch protection requires; a draft waits on neither, since its worker has yet to mark it ready. On Gitea a draft is a pull request whose title opens with `WIP:` or `[WIP]`, Gitea's default `WORK_IN_PROGRESS_PREFIXES`. Changes a reviewer requested resume the chunk only while that review was made on the pull request's head commit and the pull request's author has not commented or replied after it; once the worker pushed or replied, the chunk parks on a new review, since GitHub keeps the decision until the reviewer reviews again. The chunk's window reads the forge once a minute, which no forge's rate limit notices. A chunk resumes only into a free slot, under the limits a starting chunk meets, and stays parked until then. `do-epic <key>` starts a parked chunk's window again whatever the limits, since the chunk stays parked. do-epic sets `CHUNK_PR_PARKS=1` for each worker, so `chunk-pr merge` fails at once where the pull request awaits an approval, and the worker's run doesn't hold a slot while the pull request waits. In a repo whose config sets `merge = "human"`, the merge itself is a gate: `chunk-pr merge` leaves the pull request ready, the chunk parks on `your merge` once nothing else holds the pull request, and it resumes when the forge no longer reports the pull request open, to clean up and finish. It resumes too once the pull request conflicts with its base branch, or is behind it where GitHub's branch protection requires an up-to-date branch, so the person finds a pull request they can merge: the worker runs `chunk-pr merge` again with the flags it had, which levels the branch, passes over each item already finished, waits for the checks and leaves the pull request ready. While GitHub still computes whether the pull request merges, the chunk stays parked until the next read. Gitea reports a pull request as not mergeable also for the seconds it checks for conflicts; a read in those seconds resumes the chunk for a run that changes nothing, which is cheaper than a second read every minute to rule it out. The judge may rule such a chunk finished while its pull request is open, since its worker ends each run there. So do-epic reads a gate it could not read again before it hands the chunk on, and tells the worker once to remove a worktree whose pull request is no longer open.
|
||||
- **Human tasks.** do-epic leaves a human task's issue as the team filed it. The task gets a window of its own while it is open, no issue blocks it, and it blocks another open issue. The window DMs the human once, through the notifier of the first repo whose project config names one (the repos of the issues it holds up come first, then those of the epic's other issues; where none does, the window says so), shows as parked (`awaits a human's task`) so that it doesn't take a running slot, and polls the epic every minute until the task no longer holds up an open issue. Then the issues it held up may start. A window that starts again, as after a reboot, DMs again.
|
||||
- **Findings.** A finding about the epic's goals is filed in the epic. A finding about a repo's goals follows that repo's rules. Where unsure which, do-epic asks. A set of new items toward an epic goal needs the human's approval before work starts; a finding filed during a chunk doesn't.
|
||||
- **Finishing.** When the epic holds no open item: release-review passes on each repo the epic changed, then the items they file, then the human confirms each achieve goal and that no maintain goal has a defect. For a goal that isn't met, do-epic proposes items for approval. Then a summary comment on the epic, and closing the epic in Jira, as the very last step.
|
||||
|
||||
@@ -12,3 +12,4 @@ Everything written — chat, commit messages, comments, docs, code — is in **E
|
||||
- **Write the thing, not an introduction to it.** A sentence announcing what follows, or flagging that it deserves attention, doesn't carry anything — if it matters, it is in what follows. A bare label is fine. BANNED: `Here's the new audience text, which is the part that needs your eye:`, `One thing I changed that deserves your attention.`, `One judgment call I'd flag rather than bury.`, `Three things came along that would otherwise have been left false.` GOOD: `New audience text:`, or the list alone.
|
||||
- **Write negations as people say them.** After a verb, or after its preposition, write `doesn't <verb> anything` or `anyone`, never `<verb> nothing` or `no one`; each breach is a 🟡. BANNED: `stops nothing`, `depends on no one`, `so answering in time costs nothing`. GOOD: `doesn't stop anything`, `doesn't depend on anyone`, `so answering in time doesn't cost anything`.
|
||||
- **No contrastive tail.** `X rather than Y`, `not Y but X`, `instead of Y`: state X and stop. The rejected alternative is noise unless naming it stops a reader choosing Y. BANNED: `verified in CI rather than asserted`. GOOD: `verified in CI`.
|
||||
- **A sentence about several named things holds for each of them.** Where one sentence gives a property to several named tables, fields, flags or files, check the property in each one's source. Where it fails for one, split the sentence. BANNED, where only `repos` has the column: `Each row of the repos and labels tables has a name`. GOOD: `Each row of the repos table has a name. A row of the labels table has only its label`.
|
||||
|
||||
Reference in New Issue
Block a user