765 lines
43 KiB
Python
765 lines
43 KiB
Python
"""Open the chunk's pull request as a draft, bring its branch level with origin's default branch, mark it ready, or merge it, with gh where origin is on GitHub and tea elsewhere; once it has merged, remove the chunk's worktree and branch.
|
|
|
|
usage: chunk-pr open <title> [<body>]
|
|
chunk-pr sync
|
|
chunk-pr ready [<title>]
|
|
chunk-pr push
|
|
chunk-pr merge [--finish <ID> [--changelog <bullet> | --no-changelog]]...
|
|
chunk-pr clean
|
|
chunk-pr open-epic <epic's key> <title> [<body>]
|
|
|
|
Run it in the chunk's worktree, on the chunk's branch. ready and merge act on the branch's open
|
|
pull request only while its head is the commit checked out, so push before you run them.
|
|
|
|
Where the project's config sets `epic-branch` (`project-config --help`), a chunk's pull request
|
|
goes into its epic's working branch, which chunk-preflight or do-epic recorded for the chunk's
|
|
branch as it started or continued the chunk. There, each step below reads "origin's default
|
|
branch" as that branch, with these differences:
|
|
- merge merges the pull request itself, whatever `merge` and `wait-for-approval` say: those
|
|
govern the pull request into the default branch, which open-epic opens;
|
|
- ready and push ask for a review, where the config sets `review-request-comment`, by making
|
|
that comment on the pull request;
|
|
- clean still fast-forwards the main checkout to origin's default branch.
|
|
ready and merge fail, naming both branches, where the forge merges the pull request into another
|
|
branch than the one recorded, or than the default branch where the checkout records none. A person
|
|
then settles which holds: they change the pull request's base on the forge, or the record, which
|
|
is `branch.<branch>.chunk-base` in git's config.
|
|
|
|
open pushes the branch, setting its upstream, and opens a draft pull request into origin's
|
|
default branch. <title> is one line, as ~/.claude/CLAUDE.md → "Git, commits, and PRs"
|
|
says, and <body> is the pull request's summary. On a branch that fits the config's `branch`
|
|
template, it refuses a <title> that doesn't fit the `pull-request-title` template the
|
|
project's config names (`project-config --help`); on any other branch, as for a
|
|
chunk with no plan item, the title may be the bare summary. It fails where no config names the checkout. Where the branch's pull request is open
|
|
already, it opens no second one. On origin's default branch it refuses without pushing anything.
|
|
sync fetches origin and merges its default branch into the branch checked out, where the
|
|
branch does not hold it already, and prints which it did. Then, where the project's config
|
|
names a todo.md that exists, it runs `rank_todo.py --check` on it and prints the result,
|
|
failing where the check fails or no config names the checkout. On a merge conflict it names the conflicted files and leaves the merge in
|
|
progress, to resolve and commit. On origin's default branch it refuses and doesn't fetch anything.
|
|
ready marks the pull request ready for review. On Gitea a draft is a pull request whose title
|
|
starts with `WIP: `, so there it drops that prefix. Given <title>, one line, which it holds
|
|
to the template as open does, it sets that
|
|
as the pull request's title first; where that fails, the pull request stays a draft.
|
|
push pushes the branch, setting its upstream. Where its pull request is open and goes into an
|
|
epic's working branch, it then asks for a review as ready does. Use it for each push
|
|
after ready there, and wait for that review as for any other.
|
|
merge merges the pull request in its turn: the chunks of one project on this machine take
|
|
turns, one at a time. Run it in the background. In its turn it:
|
|
1. fetches origin and merges its default branch into the branch, as sync does;
|
|
2. finishes each plan item a --finish names with `todo-item finish`, passing on
|
|
--changelog or --no-changelog (a Jira plan takes no --changelog, as todo-item says),
|
|
and commits what that changed in the plan and the changelog, so both change only
|
|
at merge time, on top of every chunk merged before;
|
|
3. pushes, also where step 2 failed after step 1 brought changes in;
|
|
4. waits for the pull request's checks, and those origin's default branch requires, to
|
|
pass on the head; where no check reports within a minute, it takes the pull request
|
|
as having none;
|
|
5. merges the pull request, only while its head is still the commit checked out, so a
|
|
push after the gate is never merged. It takes the first merge method the repository
|
|
allows of: a merge commit, fast-forward only, a rebase followed by a merge commit, a
|
|
rebase, a squash. GitHub offers only the merge commit, the rebase and the squash.
|
|
Its last line names each --finish item the plan did not hold when it began: an earlier
|
|
run finished that item, or its ID is mistyped.
|
|
Where the project's config sets `wait-for-approval = true` (`project-config --help`), it
|
|
merges only once GitHub reports the pull request approved as its branch protection
|
|
requires. It waits for that outside its turn, so other chunks merge meanwhile, and takes
|
|
a new turn once approved. In a chunk do-epic runs, which sets CHUNK_PR_PARKS=1, it
|
|
fails at once instead of waiting: do-epic parks the chunk until the approval comes.
|
|
Where the project's config sets `merge = "human"` (`project-config --help`), it does
|
|
steps 1 to 4, marks the pull request ready in place of step 5, and prints that the pull
|
|
request awaits a person's merge, exit 0. A plan or changelog in the checkout that step 2
|
|
finished is a commit on the branch, so it lands with that merge; one in Jira, or in
|
|
the config's folder, is finished at once. It reads no approval then, whatever
|
|
`wait-for-approval` says. Once a person merged it, run clean.
|
|
It stops, without merging, and says what to do before running it again:
|
|
- on a merge conflict in step 1, naming the conflicted files, with the merge in progress;
|
|
- where `larv-review scoring-run-owed` exits 1 after step 3, because the chunk owes a
|
|
scoring run it has not recorded;
|
|
- where origin's default branch has moved since the branch last recorded a paired
|
|
ruling, since that ruling read a head that no longer merges;
|
|
- where a check fails, or, on Gitea, where the checks have not all passed within 30
|
|
minutes; on GitHub, gh watches them until they end;
|
|
- where other pull requests still hold the turn after 30 minutes, naming the last;
|
|
- with `wait-for-approval`: where a reviewer requested changes, where the protection
|
|
requires no review, on Gitea, where it cannot read the config, and after 90 minutes
|
|
without an approval;
|
|
- with `wait-for-approval`, approved or not: where a reviewer's comment waits for an
|
|
answer, which is a review thread nobody resolved whose last comment is not the pull
|
|
request author's. Answer it in its thread and push any fix.
|
|
A run that waits for an approval takes two turns, so it can last the 90 minutes and,
|
|
twice, the 30 minutes in the queue and the checks. One killed before that left the
|
|
branch pushed, so run it again.
|
|
clean acts once the forge reports the branch's pull request merged at the commit checked out,
|
|
by any merge method. It fetches origin, fast-forwards the main checkout to origin's
|
|
default branch, removes the chunk's worktree, then deletes the local branch; origin's
|
|
branch stays. Where the worktree has uncommitted or untracked files, it refuses and
|
|
doesn't touch anything. Where the main checkout has uncommitted or untracked files, another
|
|
branch checked out, or commits origin's default branch lacks, it leaves that as it was,
|
|
still removes the worktree and the branch, and fails saying why.
|
|
open-epic runs in any checkout of the repository, once the epic's last chunk has merged. It
|
|
fetches origin and brings the working branch of the epic named level with origin's
|
|
default branch, by a merge commit pushed to origin. Then it opens the pull request from
|
|
that branch into the default branch, ready and titled <title>, and leaves it to a person
|
|
to merge. Where the two don't merge cleanly it doesn't open anything and says how a
|
|
person merges them. Where the pull request is open already, it doesn't open a second
|
|
one. It fails where the config sets no `epic-branch`, or origin has no such branch, as
|
|
once its pull request has merged and the forge deleted it.
|
|
|
|
It prints what it did, exit 0, or why it failed, exit 1.
|
|
"""
|
|
import contextlib
|
|
import dataclasses
|
|
import fcntl
|
|
import functools
|
|
import json
|
|
import os
|
|
import pathlib
|
|
import sys
|
|
import time
|
|
import typing
|
|
|
|
from chunk_pr.approval import approval, approved, awaited, left_to_a_person, left_to_park, PARKS, unanswered
|
|
from forge.pulls import checks_passed, merged_pull, open_pull, other_base, required_checks
|
|
from git_cli.git_repo import CHUNK_BASE, Git
|
|
from git_cli import epic_branch
|
|
from failure import Failure
|
|
from forge.commands import Forge, forge_of, gitea, Run, runner
|
|
from atlassian.jira import ISSUE_KEY
|
|
from project_config.main import located
|
|
from project_config.settings import ProjectConfig
|
|
from plan_store.plans import says_no_item
|
|
from project_config import templates
|
|
|
|
BIN = pathlib.Path(__file__).resolve().parents[1]
|
|
# How long merge waits for a check to report before it takes a pull request without any as passed: CI queues its checks within seconds of a push, and merge may run right after one.
|
|
NO_CHECKS_SECONDS = 60
|
|
# The file, in the git folder that every worktree of the checkout shares, that a merge keeps locked with flock for its turn: so every chunk of the project on this machine queues on it.
|
|
QUEUE = "chunk-pr-merge-queue"
|
|
# A turn lasts as long as its checks, which chunk-pr waits half an hour for on Gitea, so a queue still held after that is reported, not waited out.
|
|
QUEUE_SECONDS = 30 * 60
|
|
QUEUE_POLL_SECONDS = 10
|
|
# The line record-ruling writes into the comprehension history, as git's -G reads it.
|
|
RULING = "^Ruling: "
|
|
# The project's config, loaded once per step, on the first call that needs it.
|
|
Config = typing.Callable[[], ProjectConfig | Failure]
|
|
USAGE = "usage: chunk-pr open <title> [<body>] | chunk-pr sync | chunk-pr ready [<title>] | chunk-pr push | chunk-pr merge [--finish <ID> [--changelog <bullet> | --no-changelog]]... | chunk-pr clean | chunk-pr open-epic <epic's key> <title> [<body>]"
|
|
|
|
# Each forge's merge methods in the order merge prefers them, as the repository setting that allows the method and the method's name in the forge's merge call. A merge commit and a fast-forward keep the branch's commits as they are; a rebase or a squash rewrites them.
|
|
METHODS: dict[Forge, tuple[tuple[str, str], ...]] = {
|
|
"gh": (("mergeCommitAllowed", "--merge"), ("rebaseMergeAllowed", "--rebase"), ("squashMergeAllowed", "--squash")),
|
|
"tea": (("allow_merge_commits", "merge"), ("allow_fast_forward_only_merge", "fast-forward-only"), ("allow_rebase_explicit", "rebase-merge"), ("allow_rebase", "rebase"), ("allow_squash_merge", "squash")),
|
|
}
|
|
|
|
|
|
def main(argv: list[str]) -> int:
|
|
if argv[:1] in (["-h"], ["--help"]):
|
|
print(__doc__.strip())
|
|
return 0
|
|
done = step(argv, runner(os.getcwd()), functools.cache(lambda: located(os.getcwd(), pathlib.Path.home())), os.environ.get(PARKS) == "1")
|
|
if isinstance(done, Failure):
|
|
print(f"chunk-pr: {done.reason}", file=sys.stderr)
|
|
return 1
|
|
print(done)
|
|
return 0
|
|
|
|
|
|
def step(argv: list[str], run: Run, config: Config, parks: bool = False) -> str | Failure:
|
|
"""Run the step argv names: the line to print, or a Failure. A malformed argv doesn't run anything. parks is whether a merge fails at once where it would wait for an approval (`merged`)."""
|
|
match argv:
|
|
case ["open", title, *body] if len(body) <= 1 and not title.startswith("-"):
|
|
return Failure("give a title of one line") if not one_line(title) else misfit(title, run, config) or opened(title, body[0] if body else "", run)
|
|
case ["sync"]:
|
|
return synced(run, config)
|
|
case ["ready", *title] if len(title) <= 1 and not any(given.startswith("-") for given in title):
|
|
return Failure("give a title of one line") if title and not one_line(title[0]) else (misfit(title[0], run, config) if title else None) or readied(run, title[0] if title else None, config)
|
|
# Three readers, seated as those who run `chunk-pr`, picked the spellings `push`, 3-0, and `open-epic`, 2-1.
|
|
case ["push"]:
|
|
return pushed(run, config)
|
|
case ["open-epic", epic, title, *body] if len(body) <= 1 and not any(given.startswith("-") for given in (epic, title)):
|
|
return Failure("give a title of one line") if not one_line(title) else epic_opened(epic, title, body[0] if body else "", run, config)
|
|
case ["merge", *given]:
|
|
finishes = finishes_of(given)
|
|
return Failure(USAGE) if finishes is None else merged(run, config, time.sleep, finishes=finishes, parks=parks)
|
|
case ["clean"]:
|
|
return cleaned(run)
|
|
return Failure(USAGE)
|
|
|
|
|
|
def misfit(title: str, run: Run, config: Config) -> Failure | None:
|
|
"""Why title doesn't fit the `pull-request-title` template the project's config names, as templates.misfits rules; None where it fits. A config that cannot be read fails, so that no pull request reaches the project's owners under a title they don't use."""
|
|
loaded = config()
|
|
if isinstance(loaded, Failure):
|
|
return loaded
|
|
branch = run(["git", "symbolic-ref", "--short", "HEAD"])
|
|
if isinstance(branch, Failure):
|
|
return branch
|
|
if not templates.misfits(loaded.pull_request_title, loaded.branch, branch.strip("\n"), title):
|
|
return None
|
|
return Failure(f"title the pull request as the project's config asks, `{loaded.pull_request_title}`, where {{id}} is the ID of the chunk's first item; {title.strip()!r} doesn't fit")
|
|
|
|
|
|
def one_line(title: str) -> bool:
|
|
return bool(title.strip()) and "\n" not in title
|
|
|
|
|
|
def answers(run: Run, *commands: list[str]) -> list[str] | Failure:
|
|
"""What each git command printed, stripped, or the first Failure."""
|
|
answered = [run(["git", *args]) for args in commands]
|
|
failed = next((answer for answer in answered if isinstance(answer, Failure)), None)
|
|
return failed if failed is not None else [str(answer).strip() for answer in answered]
|
|
|
|
|
|
def checkout(run: Run) -> tuple[Forge, str, str] | Failure:
|
|
"""The forge, the branch checked out and its head commit."""
|
|
found = answers(run, ["remote", "get-url", "origin"], ["symbolic-ref", "--short", "HEAD"], ["rev-parse", "HEAD"])
|
|
if isinstance(found, Failure):
|
|
return found
|
|
origin, branch, head = found
|
|
return forge_of(origin), branch, head
|
|
|
|
|
|
def default_branch(run: Run) -> str | Failure:
|
|
"""origin's default branch, such as main. It differs from git_cli's default_ref, which falls back to a local main or master and asks origin where nothing is recorded. A pull request's base is origin's alone, so this fails instead, and says how to record it."""
|
|
default = run(["git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD"])
|
|
if isinstance(default, Failure):
|
|
return Failure(f"origin records no default branch; set it with `git remote set-head origin --auto`: {default.reason}")
|
|
return default.strip().removeprefix("origin/")
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Base:
|
|
"""The branch a chunk's pull request merges into. to_epic says it is an epic's working branch, which the chunk merges into whatever the config says of the default branch: `merge = "human"` and `wait-for-approval` govern only the epic branch's own pull request (docs/decisions.md → `epic-branch: an epic's chunks branch off and merge into a working branch …`)."""
|
|
branch: str
|
|
to_epic: bool
|
|
|
|
|
|
def base_of(branch: str, run: Run) -> Base | Failure:
|
|
"""The Base of the pull request from branch: the epic's working branch the checkout records for it (`git_repo.record_chunk_base`), else origin's default branch."""
|
|
recorded = run(["git", "config", "--get", f"branch.{branch}.{CHUNK_BASE}"])
|
|
if not isinstance(recorded, Failure) and recorded.strip():
|
|
return Base(recorded.strip(), True)
|
|
default = default_branch(run)
|
|
return default if isinstance(default, Failure) else Base(default, False)
|
|
|
|
|
|
def pull(run: Run) -> tuple[Forge, str, str] | Failure:
|
|
"""The forge, the number of the branch's open pull request at its head, and that head. A Failure where the forge merges that pull request into another branch than `base_of` names: that base says whether a person merges, so no step acts while the two differ."""
|
|
found = checkout(run)
|
|
if isinstance(found, Failure):
|
|
return found
|
|
forge, branch, head = found
|
|
number = open_pull(forge, branch, head, run)
|
|
if number is None:
|
|
return Failure(f"no pull request from origin's {branch} is open at {head[:12]}; push the branch, or open one with chunk-pr open")
|
|
if isinstance(number, Failure):
|
|
return number
|
|
base = base_of(branch, run)
|
|
if isinstance(base, Failure):
|
|
return base
|
|
return other_base(forge, number, base.branch, run) or (forge, number, head)
|
|
|
|
|
|
def opened(title: str, body: str, run: Run) -> str | Failure:
|
|
found = checkout(run)
|
|
if isinstance(found, Failure):
|
|
return found
|
|
forge, branch, head = found
|
|
base = base_of(branch, run)
|
|
if isinstance(base, Failure):
|
|
return base
|
|
if branch == base.branch:
|
|
return Failure(f"{branch} is origin's default branch; open the pull request from the chunk's branch")
|
|
pushed = run(["git", "push", "--quiet", "--set-upstream", "origin", branch])
|
|
if isinstance(pushed, Failure):
|
|
return pushed
|
|
number = open_pull(forge, branch, head, run)
|
|
if isinstance(number, str):
|
|
return f"Pull request #{number} is open already."
|
|
if isinstance(number, Failure):
|
|
return number
|
|
command = ["gh", "pr", "create"] if forge == "gh" else ["tea", "pulls", "create"]
|
|
created = run([*command, "--draft", "--head", branch, "--base", base.branch, "--title", title, "--body" if forge == "gh" else "--description", body])
|
|
if isinstance(created, Failure):
|
|
return created
|
|
number = open_pull(forge, branch, head, run)
|
|
if number is None:
|
|
return Failure(f"{command[0]} created the pull request, but no pull request from origin's {branch} is listed open at {head[:12]}")
|
|
return number if isinstance(number, Failure) else f"Opened draft pull request #{number}."
|
|
|
|
|
|
def synced(run: Run, config: Config) -> str | Failure:
|
|
found = checkout(run)
|
|
if isinstance(found, Failure):
|
|
return found
|
|
_, branch, _ = found
|
|
base = base_of(branch, run)
|
|
if isinstance(base, Failure):
|
|
return base
|
|
if branch == base.branch:
|
|
return Failure(f"{branch} is origin's default branch; sync the chunk's branch")
|
|
level = levelled(run, branch, base.branch)
|
|
if isinstance(level, Failure):
|
|
return level
|
|
done = f"Merged origin/{base.branch} into {branch}." if level else f"{branch} already holds origin/{base.branch}."
|
|
loaded = config()
|
|
if isinstance(loaded, Failure):
|
|
return Failure(f"{done.removesuffix('.')}, but the plan to check cannot be found: {loaded.reason}")
|
|
todo = loaded.plan_file
|
|
# A plan in Jira is no file, and Jira's backlog ranks it.
|
|
if todo is None or not todo.is_file():
|
|
return done
|
|
ranked = run([str(BIN / "rank_todo.py"), "--check", str(todo)])
|
|
if isinstance(ranked, Failure):
|
|
return Failure(f"{done.removesuffix('.')}, but rank_todo.py --check todo.md failed: {ranked.reason}")
|
|
return f"{done}\nrank_todo.py --check todo.md passed."
|
|
|
|
|
|
def levelled(run: Run, branch: str, base: str, resolve: str = "resolve them and commit") -> bool | Failure:
|
|
"""Fetch origin and merge its base into branch, the one checked out: whether that brought anything in. On a conflict the merge stays in progress, and the Failure names the conflicted files and ends with resolve, the caller's words for what to do about them."""
|
|
fetched = run(["git", "fetch", "--quiet", "origin"])
|
|
if isinstance(fetched, Failure):
|
|
return fetched
|
|
behind = answers(run, ["rev-list", "--count", f"HEAD..origin/{base}"])
|
|
if isinstance(behind, Failure):
|
|
return behind
|
|
if behind[0] == "0":
|
|
return False
|
|
merged = run(["git", "merge", "--quiet", "--no-edit", f"origin/{base}"])
|
|
if isinstance(merged, Failure):
|
|
conflicted = answers(run, ["diff", "--name-only", "--diff-filter=U"])
|
|
if isinstance(conflicted, Failure) or not conflicted[0]:
|
|
return merged
|
|
return Failure(f"merging origin/{base} into {branch} conflicts in {', '.join(conflicted[0].splitlines())}; the merge stays in progress: {resolve}")
|
|
return True
|
|
|
|
|
|
def readied(run: Run, title: str | None, config: Config) -> str | Failure:
|
|
"""Mark the branch's pull request ready, then ask for a review of it as `review_asked` does."""
|
|
found = pull(run)
|
|
marked = found if isinstance(found, Failure) else marked_ready(run, title)
|
|
if isinstance(found, Failure) or isinstance(marked, Failure):
|
|
return marked
|
|
asked = review_asked(found[0], found[1], run, config)
|
|
if isinstance(asked, Failure):
|
|
return Failure(f"marked pull request #{found[1]} ready, but could not ask for a review: {asked.reason}")
|
|
return f"{marked[:-1]}, and asked for a review with “{asked}”." if asked else marked
|
|
|
|
|
|
def marked_ready(run: Run, title: str | None) -> str | Failure:
|
|
found = pull(run)
|
|
if isinstance(found, Failure):
|
|
return found
|
|
forge, number, _ = found
|
|
retitle = ["--title", title] if title is not None else []
|
|
if forge == "gh":
|
|
# gh marks a pull request ready only with `gh pr ready`, which takes no title.
|
|
titled = run(["gh", "pr", "edit", number, *retitle]) if retitle else ""
|
|
ready = titled if isinstance(titled, Failure) else run(["gh", "pr", "ready", number])
|
|
else:
|
|
ready = run(["tea", "pulls", "edit", number, *retitle, "--ready"])
|
|
if isinstance(ready, Failure):
|
|
return ready
|
|
return f"Marked pull request #{number} ready, titled “{title}”." if title is not None else f"Marked pull request #{number} ready."
|
|
|
|
|
|
def pushed(run: Run, config: Config) -> str | Failure:
|
|
"""Push the branch checked out, and ask for a review of its open pull request as `review_asked` does."""
|
|
found = checkout(run)
|
|
if isinstance(found, Failure):
|
|
return found
|
|
forge, branch, head = found
|
|
sent = run(["git", "push", "--quiet", "--set-upstream", "origin", branch])
|
|
number = sent if isinstance(sent, Failure) else open_pull(forge, branch, head, run)
|
|
if isinstance(number, Failure):
|
|
return number
|
|
asked = review_asked(forge, number, run, config) if number is not None else None
|
|
if isinstance(asked, Failure):
|
|
return Failure(f"pushed {branch}, but could not ask for a review: {asked.reason}")
|
|
return f"Pushed {branch}, and asked for a review of pull request #{number} with “{asked}”." if asked else f"Pushed {branch}."
|
|
|
|
|
|
def review_asked(forge: Forge, number: str, run: Run, config: Config) -> str | None | Failure:
|
|
"""Comment on the pull request numbered number with the config's `review-request-comment`, where the pull request goes into an epic's working branch: a forge's auto-reviewer may review only pull requests into the default branch unless asked. The comment made; None where the config names none or the pull request goes into the default branch."""
|
|
branch = answers(run, ["symbolic-ref", "--short", "HEAD"])
|
|
base = branch if isinstance(branch, Failure) else base_of(branch[0], run)
|
|
if isinstance(base, Failure):
|
|
return base
|
|
if not base.to_epic:
|
|
return None
|
|
loaded = config()
|
|
if isinstance(loaded, Failure) or loaded.review_request_comment is None:
|
|
return loaded if isinstance(loaded, Failure) else None
|
|
comment = loaded.review_request_comment
|
|
made = run(["gh", "pr", "comment", number, "--body", comment] if forge == "gh" else ["tea", "comment", number, comment])
|
|
return made if isinstance(made, Failure) else comment
|
|
|
|
|
|
def epic_opened(epic: str, title: str, body: str, run: Run, config: Config) -> str | Failure:
|
|
"""Bring the working branch of the epic with the key epic level with origin's default branch, then open its pull request into that branch, ready, for a person to merge."""
|
|
if not ISSUE_KEY.fullmatch(epic):
|
|
return Failure(f"{epic!r} is no epic's key, such as ABC-123")
|
|
loaded = config()
|
|
if isinstance(loaded, Failure):
|
|
return loaded
|
|
if loaded.epic_branch is None:
|
|
return Failure("the project's config sets no `epic-branch`, so the epic has no branch to open a pull request from (`project-config --help`)")
|
|
branch = templates.epic_branch(loaded.epic_branch, epic)
|
|
found = answers(run, ["remote", "get-url", "origin"])
|
|
if isinstance(found, Failure):
|
|
return found
|
|
default = default_branch(run)
|
|
if isinstance(default, Failure):
|
|
return default
|
|
forge = forge_of(found[0])
|
|
git: Git = lambda *args, cwd=None, timeout=None, guarded=False, errors="strict": run(["git", *args])
|
|
# `levelled` makes a branch origin lacks, which here would be a stray one: a mistyped key, or a branch its merge deleted.
|
|
held = epic_branch.on_origin(branch, None, None, git)
|
|
if not held:
|
|
return Failure(f"origin has no branch {branch}, so no chunk of {epic} has merged into one: check the epic's key, and whether the branch's pull request merged already")
|
|
level = held if isinstance(held, Failure) else epic_branch.levelled(branch, f"origin/{default}", run=git)
|
|
head = level if isinstance(level, Failure) else answers(run, ["rev-parse", f"origin/{branch}"])
|
|
number = head if isinstance(head, Failure) else open_pull(forge, branch, head[0], run)
|
|
if isinstance(number, Failure):
|
|
return number
|
|
if number is not None:
|
|
return f"{level} Pull request #{number} from {branch} is open already."
|
|
command = ["gh", "pr", "create"] if forge == "gh" else ["tea", "pulls", "create"]
|
|
created = run([*command, "--head", branch, "--base", default, "--title", title, "--body" if forge == "gh" else "--description", body])
|
|
return created if isinstance(created, Failure) else f"{level} Opened the pull request from {branch} into {default}, which a person merges."
|
|
|
|
|
|
def finishes_of(given: list[str]) -> list[list[str]] | None:
|
|
"""`todo-item finish`'s arguments for each item that merge's flags name, in their order; None where the flags are malformed."""
|
|
finishes, rest = [], given
|
|
while rest:
|
|
match rest:
|
|
case ["--finish", item, "--changelog", bullet, *rest] if item.isdigit():
|
|
finishes.append([item, "--changelog", bullet])
|
|
case ["--finish", item, "--no-changelog", *rest] if item.isdigit():
|
|
finishes.append([item, "--no-changelog"])
|
|
case ["--finish", item, *rest] if item.isdigit():
|
|
finishes.append([item])
|
|
case _:
|
|
return None
|
|
return finishes
|
|
|
|
|
|
def merged(run: Run, config: Config, sleep: typing.Callable[[float], None], finishes: typing.Sequence[list[str]] = (), parks: bool = False) -> str | Failure:
|
|
"""Merge the branch's pull request in the project's merge queue. Each pass of the loop is one turn in the queue; a pull request that still wants its approval leaves the queue while it waits, so the next chunk merges meanwhile, and takes a new turn once approved. Where parks, it doesn't wait for the approval: it fails at once, as `left_to_park` says. Where the project's config leaves the merge to a person, the turn ends with the pull request ready, as `left_to_a_person` says."""
|
|
found = pull(run)
|
|
if isinstance(found, Failure):
|
|
return found
|
|
forge, number, _ = found
|
|
loaded = config()
|
|
if isinstance(loaded, Failure):
|
|
return loaded
|
|
branch = answers(run, ["symbolic-ref", "--short", "HEAD"])
|
|
base = branch if isinstance(branch, Failure) else base_of(branch[0], run)
|
|
if isinstance(base, Failure):
|
|
return base
|
|
by_human = loaded.merge == "human" and not base.to_epic
|
|
waits = awaited(forge, loaded.wait_for_approval and not base.to_epic, by_human)
|
|
if isinstance(waits, Failure):
|
|
return waits
|
|
method = merge_method(forge, run)
|
|
if isinstance(method, Failure):
|
|
return method
|
|
required = required_checks(forge, base.branch, run)
|
|
if isinstance(required, Failure):
|
|
return required
|
|
queue = answers(run, ["rev-parse", "--path-format=absolute", "--git-common-dir"])
|
|
if isinstance(queue, Failure):
|
|
return queue
|
|
absent = unplanned(run, finishes)
|
|
if isinstance(absent, Failure):
|
|
return absent
|
|
file = pathlib.Path(queue[0]) / QUEUE
|
|
pull_request = Merging(forge, number, method, base.branch, required, waits, by_human)
|
|
while True:
|
|
with turn(file, number, sleep) as untaken:
|
|
taken = untaken or merge_turn(pull_request, finishes, loaded, run, sleep)
|
|
if isinstance(taken, AwaitsMerge):
|
|
return left_to_a_person(number, parks) + absent
|
|
if not isinstance(taken, AwaitsApproval):
|
|
return taken if isinstance(taken, Failure) else taken + absent
|
|
if parks:
|
|
return left_to_park(number, run)
|
|
# Out of the queue, so the project's other chunks merge while this one waits.
|
|
waited = approved(number, run, sleep)
|
|
if isinstance(waited, Failure):
|
|
return waited
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Merging:
|
|
"""A pull request that merge takes turns for: its forge and number, the merge method, the branch it merges into (`Base`) with the checks that branch requires, whether it waits for an approval, and whether a person merges it."""
|
|
forge: Forge
|
|
number: str
|
|
method: str
|
|
base: str
|
|
required: set[str]
|
|
waits: bool
|
|
by_human: bool
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class AwaitsApproval:
|
|
"""The pull request passed its checks but awaits a human's approval, so merge leaves the queue until it has one."""
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class AwaitsMerge:
|
|
"""The pull request passed its checks and is marked ready, and the project's config leaves its merge to a person."""
|
|
|
|
|
|
def merge_turn(pull_request: Merging, finishes: typing.Sequence[list[str]], config: ProjectConfig, run: Run, sleep: typing.Callable[[float], None]) -> str | AwaitsApproval | AwaitsMerge | Failure:
|
|
"""One turn in the queue: level the branch and finish its items, wait for its checks, and merge it where nothing still waits. What merged it, or why it waits or fails. A pull request a person merges is marked ready instead: its finished items are commits on its branch, so they reach the default branch with that person's merge."""
|
|
head = levelled_and_finished(run, pull_request.base, finishes, config)
|
|
checked = head if isinstance(head, Failure) else checks_passed(pull_request.forge, pull_request.number, head, pull_request.required, run, sleep, NO_CHECKS_SECONDS)
|
|
if isinstance(checked, Failure):
|
|
return checked
|
|
if pull_request.by_human:
|
|
marked = marked_ready(run, None)
|
|
return marked if isinstance(marked, Failure) else AwaitsMerge()
|
|
ready = approval(pull_request.number, run) if pull_request.waits else True
|
|
if isinstance(ready, Failure):
|
|
return ready
|
|
if not ready:
|
|
return AwaitsApproval()
|
|
asked = unanswered(pull_request.number, run) if pull_request.waits else None
|
|
if asked is not None:
|
|
return asked
|
|
# A person may have changed the pull request's base since the turn began, as while its checks ran.
|
|
if moved := other_base(pull_request.forge, pull_request.number, pull_request.base, run):
|
|
return moved
|
|
if pull_request.forge == "gh":
|
|
done = run(["gh", "pr", "merge", pull_request.number, pull_request.method, "--match-head-commit", str(head)])
|
|
else:
|
|
done = gitea(run, f"repos/{{owner}}/{{repo}}/pulls/{pull_request.number}/merge", f"Do={pull_request.method}", f"head_commit_id={head}")
|
|
return done if isinstance(done, Failure) else f"Merged pull request #{pull_request.number} ({pull_request.method.removeprefix('--')})."
|
|
|
|
|
|
def unplanned(run: Run, finishes: typing.Sequence[list[str]]) -> str | Failure:
|
|
"""A sentence for merge's last line, naming each item of finishes the plan doesn't hold as merge begins: an earlier run finished it, or its ID is mistyped, and only the reader can tell which. Empty where the plan holds them all."""
|
|
absent = []
|
|
for finish in finishes:
|
|
shown = run([str(BIN / "todo-item"), "show", finish[0]])
|
|
if isinstance(shown, Failure) and not says_no_item(shown.reason, finish[0]):
|
|
return shown
|
|
absent += [finish[0]] if isinstance(shown, Failure) else []
|
|
return f" The plan held no item {', '.join(absent)} when merge began, so merge left the plan as it was there." if absent else ""
|
|
|
|
|
|
@contextlib.contextmanager
|
|
def turn(queue: pathlib.Path, number: str, sleep: typing.Callable[[float], None]) -> typing.Iterator[Failure | None]:
|
|
"""Hold the project's merge queue as pull request number: wait until no other chunk-pr merge on this machine holds it, and free it on the way out, however that is. Gives None while it holds the queue; a Failure, without the queue, where another merge still holds it after QUEUE_SECONDS or the file cannot be opened or locked."""
|
|
try:
|
|
fd = os.open(queue, os.O_RDWR | os.O_CREAT, 0o644)
|
|
except OSError as failure:
|
|
yield Failure(f"cannot take a turn in the merge queue, {queue}: {failure.strerror}")
|
|
return
|
|
try:
|
|
yield held_turn(fd, queue, number, sleep)
|
|
finally:
|
|
os.close(fd)
|
|
|
|
|
|
def held_turn(fd: int, queue: pathlib.Path, number: str, sleep: typing.Callable[[float], None]) -> Failure | None:
|
|
"""Lock the open queue file fd for pull request number and write its number there, for a merge that waits to name; None once held, else why it isn't."""
|
|
try:
|
|
for waited in range(0, QUEUE_SECONDS + 1, QUEUE_POLL_SECONDS):
|
|
try:
|
|
fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
|
|
break
|
|
except BlockingIOError:
|
|
if waited == QUEUE_SECONDS:
|
|
holder = os.pread(fd, 20, 0).decode(errors="replace").strip()
|
|
return Failure(f"the merge queue stayed held for {QUEUE_SECONDS // 60} minutes, last by pull request #{holder or '?'}, so this one took no turn; run chunk-pr merge again")
|
|
sleep(QUEUE_POLL_SECONDS)
|
|
os.ftruncate(fd, 0)
|
|
os.pwrite(fd, number.encode(), 0)
|
|
except OSError as failure:
|
|
return Failure(f"cannot take a turn in the merge queue, {queue}: {failure.strerror}")
|
|
return None
|
|
|
|
|
|
def levelled_and_finished(run: Run, base: str, finishes: typing.Sequence[list[str]], config: ProjectConfig) -> str | Failure:
|
|
"""What merge does to the branch inside its turn, before the checks: merge origin's base into it, finish the plan items, and push. The head to merge, or why the worker must act first. Whatever it committed is pushed before it fails, so the pull request's head stays the commit checked out."""
|
|
found = checkout(run)
|
|
if isinstance(found, Failure):
|
|
return found
|
|
_, branch, before = found
|
|
moved = levelled(run, branch, base, "resolve them, commit, push, and run chunk-pr merge again")
|
|
if isinstance(moved, Failure):
|
|
return moved
|
|
failed = next((failure for finish in finishes if (failure := finished(run, branch, finish, config))), None)
|
|
head = answers(run, ["rev-parse", "HEAD"])
|
|
if isinstance(head, Failure):
|
|
return head
|
|
pushed = run(["git", "push", "--quiet", "origin", branch]) if head[0] != before else ""
|
|
if isinstance(pushed, Failure):
|
|
return pushed
|
|
# The scoring run is asked for only now: scoring-run-owed counts as shipped the items the committed plan no longer holds.
|
|
owed = failed or run([str(BIN / "larv-review"), "scoring-run-owed"])
|
|
if isinstance(owed, Failure):
|
|
return owed
|
|
return remeasure(run, base, config) or head[0]
|
|
|
|
|
|
def finished(run: Run, branch: str, finish: list[str], config: ProjectConfig) -> Failure | None:
|
|
"""Finish one plan item with `todo-item finish` and commit what that changed. An item the plan no longer holds was finished by an earlier run of merge, which may have stopped before its commit: so the plan and the changelog are committed either way."""
|
|
shown = run([str(BIN / "todo-item"), "show", finish[0]])
|
|
if isinstance(shown, Failure) and not says_no_item(shown.reason, finish[0]):
|
|
return shown
|
|
finishing = "" if isinstance(shown, Failure) else run([str(BIN / "todo-item"), "finish", *finish])
|
|
if isinstance(finishing, Failure):
|
|
return finishing
|
|
title = templates.title_of(config.commit_title, config.branch, branch, finish[0], f"Finish item {finish[0]} in the plan")
|
|
# Under `merge = "human"` a plan or changelog outside the checkout is finished here, before the person merges, since no run follows that merge.
|
|
# A plan in Jira, or a changelog on a Confluence page, is no file to commit.
|
|
records = [record for record in (config.plan_file, config.paths.get("changelog")) if record is not None and record.is_file()]
|
|
return committed(run, title, records)
|
|
|
|
|
|
def committed(run: Run, title: str, files: list[pathlib.Path]) -> Failure | None:
|
|
"""Commit what changed in files under title, each in the git repository that holds it, and only those files: a record the config keeps in its own folder is committed there, where another chunk may commit at the same time."""
|
|
held: dict[str, list[str]] = {}
|
|
for file in files:
|
|
top = run(["git", "-C", str(file.parent), "rev-parse", "--show-toplevel"])
|
|
if isinstance(top, Failure):
|
|
return top
|
|
held.setdefault(top.strip(), []).append(str(file))
|
|
for top, paths in held.items():
|
|
changed = run(["git", "-C", top, "status", "--porcelain", "--", *paths])
|
|
steps = [changed] if isinstance(changed, Failure) or not changed.strip() else [run(["git", "-C", top, "add", "--", *paths]), run(["git", "-C", top, "commit", "--quiet", "-m", title, "--", *paths])]
|
|
if failed := next((step for step in steps if isinstance(step, Failure)), None):
|
|
return failed
|
|
return None
|
|
|
|
|
|
def remeasure(run: Run, base: str, config: ProjectConfig) -> Failure | None:
|
|
"""A Failure where origin's base has moved since the branch last recorded a paired ruling: that ruling read a head that no longer merges. None where the branch recorded none, or the project keeps its history outside the checkout."""
|
|
history = config.paths.get("comprehension-history")
|
|
# A history on a Confluence page is outside the checkout.
|
|
if history is None:
|
|
return None
|
|
top = answers(run, ["rev-parse", "--show-toplevel"])
|
|
if isinstance(top, Failure) or not history.resolve().is_relative_to(top[0]):
|
|
return top if isinstance(top, Failure) else None
|
|
ruled = answers(run, ["log", "-1", "--format=%H", "-G", RULING, f"origin/{base}..HEAD", "--", str(history)])
|
|
if isinstance(ruled, Failure) or not ruled[0].strip():
|
|
return ruled if isinstance(ruled, Failure) else None
|
|
since = answers(run, ["rev-list", "--count", f"{ruled[0].strip()}..origin/{base}"])
|
|
if isinstance(since, Failure) or since[0].strip() == "0":
|
|
return since if isinstance(since, Failure) else None
|
|
return Failure(f"origin/{base} moved after the branch recorded its paired ruling, and its changes are merged in and pushed; run the paired ruling again at the new head, record it, push, and run chunk-pr merge again")
|
|
|
|
|
|
def merge_method(forge: Forge, run: Run) -> str | Failure:
|
|
"""The first of METHODS[forge] that the repository's settings allow."""
|
|
if forge == "gh":
|
|
viewed = run(["gh", "repo", "view", "--json", ",".join(setting for setting, _ in METHODS["gh"])])
|
|
try:
|
|
settings = viewed if isinstance(viewed, Failure) else json.loads(viewed)
|
|
except ValueError:
|
|
return Failure(f"gh repo view printed no JSON: {str(viewed).strip()[:200]}")
|
|
else:
|
|
settings = gitea(run, "repos/{owner}/{repo}")
|
|
if isinstance(settings, Failure):
|
|
return settings
|
|
allowed = next((method for setting, method in METHODS[forge] if isinstance(settings, dict) and settings.get(setting) is True), None)
|
|
return allowed if allowed is not None else Failure(f"the repository allows none of the merge methods chunk-pr knows: {', '.join(method for _, method in METHODS[forge])}")
|
|
|
|
|
|
@dataclasses.dataclass(frozen=True)
|
|
class Chunk:
|
|
"""A merged chunk's worktree and branch, the main checkout of their repository, and origin's default branch."""
|
|
worktree: str
|
|
branch: str
|
|
main: str
|
|
default: str
|
|
|
|
|
|
def cleaned(run: Run, at: typing.Callable[[str], Run] = runner) -> str | Failure:
|
|
"""Remove the worktree and branch of the merged chunk run is in, and fast-forward the main checkout; at(folder) runs commands in folder, here the main checkout."""
|
|
chunk = merged_chunk(run)
|
|
if isinstance(chunk, Failure):
|
|
return chunk
|
|
at_main = at(chunk.main)
|
|
left = kept_as_it_was(at_main, chunk.default)
|
|
files = unsaved(run)
|
|
if isinstance(files, Failure):
|
|
return files
|
|
if files:
|
|
also = f"\nIt would also have left {chunk.main} as it was: {left}" if left else ""
|
|
return Failure(f"left everything as it was: {chunk.worktree} has uncommitted or untracked files:\n{files}{also}")
|
|
return removed(chunk, at_main, left)
|
|
|
|
|
|
def merged_chunk(run: Run) -> Chunk | Failure:
|
|
"""The chunk run is in, once the forge reports its pull request merged at its head. It fetches origin, so the main checkout can fast-forward to the merge."""
|
|
found = checkout(run)
|
|
if isinstance(found, Failure):
|
|
return found
|
|
forge, branch, head = found
|
|
default = default_branch(run)
|
|
if isinstance(default, Failure):
|
|
return default
|
|
folders = worktree_and_main(run)
|
|
if isinstance(folders, Failure):
|
|
return folders
|
|
number = merged_pull(forge, branch, head, run)
|
|
if number is None:
|
|
return Failure(f"no merged pull request from {branch} at {head[:12]}, so its worktree and branch stay")
|
|
fetched = number if isinstance(number, Failure) else run(["git", "fetch", "--quiet", "origin"])
|
|
return fetched if isinstance(fetched, Failure) else Chunk(folders[0], branch, folders[1], default)
|
|
|
|
|
|
def worktree_and_main(run: Run) -> tuple[str, str] | Failure:
|
|
"""The worktree run is in, and the main checkout of its repository. Run in the main checkout itself, it fails."""
|
|
folders = answers(run, ["rev-parse", "--show-toplevel"], ["worktree", "list", "--porcelain"])
|
|
if isinstance(folders, Failure):
|
|
return folders
|
|
# git lists the main checkout first.
|
|
worktree, main = folders[0], folders[1].splitlines()[0].removeprefix("worktree ")
|
|
return Failure(f"{main} is the main checkout; run clean in the chunk's worktree") if worktree == main else (worktree, main)
|
|
|
|
|
|
def unsaved(run: Run) -> str | Failure:
|
|
"""The uncommitted and untracked files of the checkout run is in, as git status lists them; empty where there are none."""
|
|
status = run(["git", "status", "--porcelain"])
|
|
return status if isinstance(status, Failure) else status.rstrip()
|
|
|
|
|
|
def kept_as_it_was(at_main: Run, default: str) -> str | None:
|
|
"""Why the main checkout must not move, or None where it may fast-forward to origin's default."""
|
|
branch = at_main(["git", "symbolic-ref", "--quiet", "--short", "HEAD"])
|
|
if isinstance(branch, Failure) or branch.strip() != default:
|
|
return f"it has {'no branch' if isinstance(branch, Failure) else branch.strip()} checked out, not {default}"
|
|
files = unsaved(at_main)
|
|
if isinstance(files, Failure):
|
|
return files.reason
|
|
if files:
|
|
return f"it has uncommitted or untracked files:\n{files}"
|
|
if isinstance(at_main(["git", "merge-base", "--is-ancestor", "HEAD", f"origin/{default}"]), Failure):
|
|
return f"it holds commits origin/{default} lacks"
|
|
return None
|
|
|
|
|
|
def removed(chunk: Chunk, at_main: Run, left: str | None) -> str | Failure:
|
|
"""Fast-forward the main checkout unless left says why not, then remove the chunk's worktree and branch. Every command runs in the main checkout, since the worktree is gone after the removal."""
|
|
if left is None:
|
|
forwarded = at_main(["git", "merge", "--quiet", "--ff-only", f"origin/{chunk.default}"])
|
|
if isinstance(forwarded, Failure):
|
|
return forwarded
|
|
removal = at_main(["git", "worktree", "remove", chunk.worktree])
|
|
# Not -d: merged_chunk found the forge's pull request merged at the branch's head. -d would compare the branch with the main checkout's HEAD or its upstream instead, and after a rebase or squash merge neither need hold its commits.
|
|
deleted = removal if isinstance(removal, Failure) else at_main(["git", "branch", "--quiet", "-D", chunk.branch])
|
|
if isinstance(deleted, Failure):
|
|
return deleted
|
|
done = f"Removed worktree {chunk.worktree} and branch {chunk.branch}"
|
|
if left is not None:
|
|
return Failure(f"{done}, but left {chunk.main} as it was: {left}")
|
|
return f"{done}, and fast-forwarded {chunk.main} to origin/{chunk.default}."
|