basstler-stack 4.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. basstler/maintenance/__init__.py +0 -0
  2. basstler/maintenance/__main__.py +128 -0
  3. basstler/maintenance/board.py +113 -0
  4. basstler/maintenance/check_overview.py +80 -0
  5. basstler/maintenance/commands.py +595 -0
  6. basstler/maintenance/default_branch_sync.py +444 -0
  7. basstler/maintenance/exceptions.py +36 -0
  8. basstler/maintenance/fast_forward.py +223 -0
  9. basstler/maintenance/finish_summary.py +515 -0
  10. basstler/maintenance/fork_pull_request_action.py +38 -0
  11. basstler/maintenance/landed_closing.py +85 -0
  12. basstler/maintenance/landed_closing_follow_up.py +85 -0
  13. basstler/maintenance/promotion.py +248 -0
  14. basstler/maintenance/promotion_context.py +221 -0
  15. basstler/maintenance/report.py +304 -0
  16. basstler/maintenance/restack_procedure.py +279 -0
  17. basstler/maintenance/restack_steps.py +769 -0
  18. basstler/maintenance/upstream_pull_request_synchronization.py +189 -0
  19. basstler/maintenance/upstream_read_route.py +37 -0
  20. basstler/stack/__init__.py +0 -0
  21. basstler/stack/__main__.py +377 -0
  22. basstler/stack/branch_status.py +54 -0
  23. basstler/stack/checkout.py +416 -0
  24. basstler/stack/commit_move.py +218 -0
  25. basstler/stack/exceptions.py +233 -0
  26. basstler/stack/label_write.py +68 -0
  27. basstler/stack/merge_probe.py +195 -0
  28. basstler/stack/model.py +696 -0
  29. basstler/stack/promotability.py +103 -0
  30. basstler/stack/promotion_link.py +138 -0
  31. basstler/stack/report.py +304 -0
  32. basstler/stack/settings.py +453 -0
  33. basstler/stack/stack.toml +31 -0
  34. basstler_stack-4.2.0.dist-info/METADATA +16 -0
  35. basstler_stack-4.2.0.dist-info/RECORD +38 -0
  36. basstler_stack-4.2.0.dist-info/WHEEL +4 -0
  37. basstler_stack-4.2.0.dist-info/licenses/LICENSE +202 -0
  38. basstler_stack-4.2.0.dist-info/licenses/NOTICE +13 -0
@@ -0,0 +1,444 @@
1
+ """
2
+ Fast-forward the base branch sessions start from, and the fork's copy of it, to the
3
+ upstream this fork tracks.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ import sys
9
+ from dataclasses import dataclass
10
+ from enum import StrEnum
11
+ from pathlib import Path
12
+
13
+ from basstler.exit_codes import CommandFailure
14
+ from basstler.git.commands import GitCommandRunner
15
+ from basstler.github.repository import MalformedRepositoryError
16
+ from basstler.maintenance.fast_forward import (
17
+ FastForwardOutcome,
18
+ ForkBaseFastForward,
19
+ RefusedPushHandling,
20
+ )
21
+ from basstler.stack.settings import Configuration
22
+
23
+ FOLLOW_UP_ROW_INDENT = " "
24
+ """
25
+ What each row under the outcome is indented by, matching the setup line's rows.
26
+ """
27
+
28
+
29
+ class BaseOutcome(StrEnum):
30
+ """
31
+ What became of this clone's copy of the upstream's base branch.
32
+ """
33
+
34
+ NOT_SYNCED = "not-synced"
35
+ """
36
+ No upstream could be resolved, so there was nothing to catch up with.
37
+ """
38
+
39
+ UPSTREAM_UNREACHABLE = "upstream-unreachable"
40
+ """
41
+ The upstream is named but could not be fetched, so how stale the clone is stays
42
+ unknown.
43
+ """
44
+
45
+ DIVERGED = "diverged"
46
+ """
47
+ The base carries commits the upstream does not, which a fast-forward cannot
48
+ reconcile and a force push must never resolve.
49
+ """
50
+
51
+ LOCAL_UPDATE_REFUSED = "local-update-refused"
52
+ """
53
+ The base is checked out with changes git will not overwrite.
54
+ """
55
+
56
+ CURRENT = "current"
57
+ """
58
+ The base already carried the upstream's tip.
59
+ """
60
+
61
+ FAST_FORWARDED = "fast-forwarded"
62
+ """
63
+ The base was behind and has been brought up to the upstream's tip.
64
+ """
65
+
66
+ @property
67
+ def carries_upstream_tip(self) -> bool:
68
+ """
69
+ :return: Whether the base ends the pass at the upstream's tip.
70
+ """
71
+ return self in {BaseOutcome.CURRENT, BaseOutcome.FAST_FORWARDED}
72
+
73
+
74
+ @dataclass(frozen=True)
75
+ class DefaultBranchReport:
76
+ """
77
+ What one catching-up pass did, and what it leaves for the session to do.
78
+ """
79
+
80
+ outcome: BaseOutcome
81
+ """
82
+ What became of this clone's copy of the base.
83
+ """
84
+
85
+ base_branch: str = ""
86
+ """
87
+ The branch caught up, as the upstream names it.
88
+ """
89
+
90
+ upstream: str = ""
91
+ """
92
+ The upstream, as ``owner/name``.
93
+ """
94
+
95
+ reason: str = ""
96
+ """
97
+ Why nothing was synced, in the words the resolution refused with.
98
+ """
99
+
100
+ commits_behind: int = 0
101
+ """
102
+ How many commits this clone's base was behind the upstream.
103
+ """
104
+
105
+ fork_remote: str = ""
106
+ """
107
+ The remote the fork's copy was published to.
108
+ """
109
+
110
+ fork_fast_forward: FastForwardOutcome | None = None
111
+ """
112
+ What became of the fork's copy, absent when it was not attempted.
113
+ """
114
+
115
+ checked_out_branch: str = ""
116
+ """
117
+ The branch the session is on, empty when it is the base or no branch at all.
118
+ """
119
+
120
+ checked_out_branch_fast_forwarded: int = 0
121
+ """
122
+ How many commits the checked-out branch was fast-forwarded onto the base.
123
+ """
124
+
125
+ checked_out_branch_behind: int = 0
126
+ """
127
+ How many commits the checked-out branch is still behind the base.
128
+ """
129
+
130
+ @property
131
+ def outcome_line(self) -> str:
132
+ """
133
+ :return: The first line of the report, saying what became of the base.
134
+ """
135
+ match self.outcome:
136
+ case BaseOutcome.NOT_SYNCED:
137
+ return f"not synced - {self.reason}"
138
+ case BaseOutcome.UPSTREAM_UNREACHABLE:
139
+ return f"'{self.base_branch}' left as it is - {self.upstream} is unreachable"
140
+ case BaseOutcome.DIVERGED:
141
+ return (
142
+ f"'{self.base_branch}' has commits {self.upstream} does not - "
143
+ f"left as it is, nothing force-pushed"
144
+ )
145
+ case BaseOutcome.LOCAL_UPDATE_REFUSED:
146
+ return (
147
+ f"'{self.base_branch}' is behind {self.upstream} but is checked out "
148
+ f"with changes git will not overwrite - left as it is"
149
+ )
150
+ case BaseOutcome.CURRENT:
151
+ return f"'{self.base_branch}' already matches {self.upstream}"
152
+ case BaseOutcome.FAST_FORWARDED:
153
+ return (
154
+ f"'{self.base_branch}' fast-forwarded {self.commits_behind} "
155
+ f"commit(s) to {self.upstream}"
156
+ )
157
+
158
+ @property
159
+ def follow_up_rows(self) -> tuple[str, ...]:
160
+ """
161
+ :return: What is left for the session to do, one row each.
162
+ """
163
+ rows = []
164
+ match self.fork_fast_forward:
165
+ case FastForwardOutcome.PUSHED:
166
+ rows.append(f"pushed it to '{self.fork_remote}', which was behind")
167
+ case FastForwardOutcome.PUSH_REFUSED:
168
+ rows.append(
169
+ f"pushing it to '{self.fork_remote}' was refused - the fork is "
170
+ f"still behind, so the next clone starts stale"
171
+ )
172
+ case FastForwardOutcome.REFUSED_NOT_FAST_FORWARD:
173
+ rows.append(
174
+ f"'{self.fork_remote}' has commits {self.upstream} does not - left "
175
+ f"as it is, nothing force-pushed, so the next clone starts stale"
176
+ )
177
+ case None if self.outcome.carries_upstream_tip:
178
+ rows.append(
179
+ f"no upstream is named, so this follows '{self.fork_remote}' itself"
180
+ )
181
+ if self.checked_out_branch_fast_forwarded:
182
+ rows.append(
183
+ f"fast-forwarded '{self.checked_out_branch}' "
184
+ f"{self.checked_out_branch_fast_forwarded} commit(s) onto "
185
+ f"'{self.base_branch}' - it had no commits of its own"
186
+ )
187
+ if self.checked_out_branch_behind:
188
+ rows.append(
189
+ f"this branch is {self.checked_out_branch_behind} commit(s) behind "
190
+ f"'{self.base_branch}' - merge or rebase it before planning on a stale base"
191
+ )
192
+ return tuple(rows)
193
+
194
+ def render(self) -> str:
195
+ """
196
+ :return: The outcome, then each follow-up row indented beneath it.
197
+ """
198
+ return "\n".join(
199
+ [
200
+ self.outcome_line,
201
+ *(f"{FOLLOW_UP_ROW_INDENT}{row}" for row in self.follow_up_rows),
202
+ ]
203
+ )
204
+
205
+
206
+ @dataclass(frozen=True)
207
+ class BaseSource:
208
+ """
209
+ Where the base is caught up from, and where the result is published.
210
+ """
211
+
212
+ base_branch: str
213
+ """
214
+ The branch every session starts from.
215
+ """
216
+
217
+ location: str
218
+ """
219
+ The remote name or URL the base is fetched from.
220
+ """
221
+
222
+ remote_name: str
223
+ """
224
+ The remote whose tracking refs the fetched base is kept under.
225
+ """
226
+
227
+ name: str
228
+ """
229
+ The repository caught up with, as ``owner/name`` where it can be read.
230
+ """
231
+
232
+ fork_remote: str
233
+ """
234
+ The fork's remote, or the clone's own remote when no upstream is named.
235
+ """
236
+
237
+ publishes_to_fork: bool
238
+ """
239
+ Whether the fork's copy is a separate copy that needs bringing level too.
240
+ """
241
+
242
+ @classmethod
243
+ def from_configuration(cls, configuration: Configuration) -> BaseSource:
244
+ """
245
+ :param configuration: The resolved stacked-PR configuration.
246
+ :return: The upstream it names, published to the fork after; or, for a project
247
+ naming none, the clone's own remote.
248
+ """
249
+ return cls(
250
+ base_branch=configuration.upstream_base,
251
+ location=configuration.upstream_location,
252
+ remote_name=configuration.upstream_remote,
253
+ name=(
254
+ configuration.upstream_repository or configuration.fork_repository
255
+ ).full_name,
256
+ fork_remote=configuration.fork_remote,
257
+ publishes_to_fork=configuration.has_upstream,
258
+ )
259
+
260
+
261
+ @dataclass(frozen=True)
262
+ class DefaultBranchSync:
263
+ """
264
+ Catches one clone's copy of the base branch up, and the fork's after it.
265
+ """
266
+
267
+ source: BaseSource
268
+ """
269
+ Where the base is caught up from, and where it is published.
270
+ """
271
+
272
+ git: GitCommandRunner
273
+ """
274
+ The runner every git command against the clone goes through.
275
+ """
276
+
277
+ @classmethod
278
+ def catch_up_checkout(cls, project_root: Path) -> DefaultBranchReport:
279
+ """
280
+ Resolve this checkout's upstream - or, when it names none, its own remote - and
281
+ catch its base up, reporting rather than raising whatever stops it.
282
+
283
+ :param project_root: The clone to catch up, which must be the current directory,
284
+ since the configuration resolves the project from it.
285
+ :return: What was done.
286
+ """
287
+ try:
288
+ source = BaseSource.from_configuration(Configuration.load())
289
+ return cls(source, GitCommandRunner(project_root)).run()
290
+ except (CommandFailure, MalformedRepositoryError) as refusal:
291
+ return DefaultBranchReport(BaseOutcome.NOT_SYNCED, reason=str(refusal))
292
+
293
+ @property
294
+ def base_branch(self) -> str:
295
+ """
296
+ :return: The branch every session starts from.
297
+ """
298
+ return self.source.base_branch
299
+
300
+ @property
301
+ def upstream_tracking_reference(self) -> str:
302
+ """
303
+ The ref the upstream's base is fetched into - the one the stacked-PR tooling reads
304
+ it from, whether or not this clone has added the upstream as a remote.
305
+ """
306
+ return f"refs/remotes/{self.source.remote_name}/{self.base_branch}"
307
+
308
+ @property
309
+ def local_reference(self) -> str:
310
+ """
311
+ :return: This clone's own copy of the base.
312
+ """
313
+ return f"refs/heads/{self.base_branch}"
314
+
315
+ def report(self, outcome: BaseOutcome, **details: object) -> DefaultBranchReport:
316
+ """
317
+ :param outcome: What became of the base.
318
+ :param details: The rest of the report's fields.
319
+ :return: The report, naming this pass's base and upstream.
320
+ """
321
+ return DefaultBranchReport(
322
+ outcome=outcome,
323
+ base_branch=self.base_branch,
324
+ upstream=self.source.name,
325
+ fork_remote=self.source.fork_remote,
326
+ **details,
327
+ )
328
+
329
+ def run(self) -> DefaultBranchReport:
330
+ """
331
+ Catch the base up, then the fork's copy of it.
332
+
333
+ :return: What was done, and what is left for the session to do.
334
+ """
335
+ if not self.git.fetch_branch(
336
+ self.source.location, self.base_branch, self.source.remote_name
337
+ ).succeeded:
338
+ return self.report(BaseOutcome.UPSTREAM_UNREACHABLE)
339
+ upstream_tip = self.git.commit_at(self.upstream_tracking_reference)
340
+ local_tip = self.git.commit_or_none(self.local_reference)
341
+
342
+ commits_behind = 0
343
+ if local_tip is not None and local_tip != upstream_tip:
344
+ if not self.git.contains(local_tip, upstream_tip):
345
+ return self.report(BaseOutcome.DIVERGED)
346
+ commits_behind = int(
347
+ self.git.run("rev-list", "--count", f"{local_tip}..{upstream_tip}")
348
+ )
349
+ if local_tip != upstream_tip and not self.move_local_base(
350
+ local_tip, upstream_tip
351
+ ):
352
+ return self.report(BaseOutcome.LOCAL_UPDATE_REFUSED)
353
+
354
+ return self.report(
355
+ BaseOutcome.FAST_FORWARDED if commits_behind else BaseOutcome.CURRENT,
356
+ commits_behind=commits_behind,
357
+ fork_fast_forward=self.publish_to_fork(),
358
+ **self.catch_up_checked_out_branch(upstream_tip),
359
+ )
360
+
361
+ def catch_up_checked_out_branch(self, base_tip: str) -> dict[str, object]:
362
+ """
363
+ Fast-forward the checked-out branch onto the base when it has no commits of its
364
+ own, and otherwise measure how far behind the base it is.
365
+
366
+ A branch with nothing of its own is one a session was cut onto from a stale
367
+ base, before this pass ran; moving it changes no work. A dirty tree that the
368
+ fast-forward would overwrite stops it, in which case the branch is reported
369
+ behind like one with work on it.
370
+
371
+ :param base_tip: The commit the base now points at.
372
+ :return: The report's checked-out-branch fields.
373
+ """
374
+ branch = self.git.attempt("branch", "--show-current").output
375
+ behind = int(self.git.run("rev-list", "--count", f"HEAD..{base_tip}"))
376
+ if not branch or branch == self.base_branch or not behind:
377
+ return {"checked_out_branch_behind": behind}
378
+ head = self.git.commit_at("HEAD")
379
+ if self.git.contains(head, base_tip) and (
380
+ self.git.attempt("merge", "--ff-only", "--quiet", base_tip).succeeded
381
+ ):
382
+ return {
383
+ "checked_out_branch": branch,
384
+ "checked_out_branch_fast_forwarded": behind,
385
+ }
386
+ return {"checked_out_branch": branch, "checked_out_branch_behind": behind}
387
+
388
+ def move_local_base(self, local_tip: str | None, upstream_tip: str) -> bool:
389
+ """
390
+ Fast-forward this clone's base onto the upstream's tip.
391
+
392
+ Two ways to move the same ref, because git refuses to fetch into the branch that is
393
+ checked out: a fast-forward merge when the session is sitting on the base, and a
394
+ ref update guarded by the old tip otherwise, which needs no working-tree change.
395
+
396
+ :param local_tip: Where the base points now, ``None`` if this clone has none.
397
+ :param upstream_tip: Where it is to point.
398
+ :return: Whether it moved.
399
+ """
400
+ if self.git.attempt("branch", "--show-current").output == self.base_branch:
401
+ return self.git.attempt(
402
+ "merge", "--ff-only", "--quiet", upstream_tip
403
+ ).succeeded
404
+ return self.git.attempt(
405
+ "update-ref", self.local_reference, upstream_tip, local_tip or ""
406
+ ).succeeded
407
+
408
+ def publish_to_fork(self) -> FastForwardOutcome | None:
409
+ """
410
+ Bring the fork's copy of the base level with the upstream's tip too.
411
+
412
+ Decided on the fork's own evidence rather than on the local base having moved: a
413
+ clone whose base was already current still leaves every later clone stale if an
414
+ earlier session's push was refused and nobody noticed.
415
+
416
+ :return: What became of the fork's copy, ``None`` when there is no separate
417
+ fork.
418
+ """
419
+ if not self.source.publishes_to_fork:
420
+ return None
421
+ return (
422
+ ForkBaseFastForward(
423
+ self.git,
424
+ self.source.fork_remote,
425
+ self.base_branch,
426
+ RefusedPushHandling.REPORTED,
427
+ )
428
+ .onto(self.upstream_tracking_reference)
429
+ .outcome
430
+ )
431
+
432
+
433
+ def main() -> int:
434
+ """
435
+ Catch the current checkout's base up and print what was done.
436
+
437
+ :return: The process exit code, 0 whatever the outcome.
438
+ """
439
+ print(DefaultBranchSync.catch_up_checkout(Path.cwd()).render())
440
+ return 0
441
+
442
+
443
+ if __name__ == "__main__":
444
+ sys.exit(main())
@@ -0,0 +1,36 @@
1
+ """
2
+ The failures the maintenance executor refuses its own output with.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+
9
+ from basstler.exceptions import DataclassException
10
+
11
+
12
+ @dataclass
13
+ class MarkdownLinkTargetError(DataclassException, ValueError):
14
+ """
15
+ Raised when a markdown link would point at something that is neither a web URL nor
16
+ an anchor on the same page.
17
+ """
18
+
19
+ label: str
20
+ """
21
+ The text the link was to show.
22
+ """
23
+
24
+ target: str
25
+ """
26
+ What it was to point at.
27
+ """
28
+
29
+ def error_message(self) -> str:
30
+ return (
31
+ f"the link '{self.label}' would point at {self.target!r}, which is neither "
32
+ f"a web URL nor an anchor"
33
+ )
34
+
35
+ def suggest_correction(self) -> str:
36
+ return "Build the target from structured data rather than from free text."
@@ -0,0 +1,223 @@
1
+ """
2
+ Moving the fork's copy of the upstream base onto the upstream's tip.
3
+
4
+ This is the step that closes the pull requests based on that branch whose work has landed,
5
+ since GitHub marks one merged the moment its head becomes an ancestor of its base. One based on
6
+ another branch is not closed by it.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass
12
+ from enum import StrEnum
13
+
14
+ from basstler.git.commands import GitCommandRunner, ProposedPush
15
+ from basstler.stack.settings import Configuration
16
+
17
+
18
+ class FastForwardOutcome(StrEnum):
19
+ """
20
+ What became of the fork's base branch.
21
+ """
22
+
23
+ PUSHED = "pushed"
24
+ """
25
+ It was moved onto the upstream's tip.
26
+ """
27
+
28
+ ALREADY_CURRENT = "already-current"
29
+ """
30
+ It already pointed at the upstream's tip.
31
+ """
32
+
33
+ REFUSED_NOT_FAST_FORWARD = "refused-not-fast-forward"
34
+ """
35
+ It carries commits the upstream does not, so moving it would discard them.
36
+ """
37
+
38
+ PUSH_REFUSED = "push-refused"
39
+ """
40
+ The fork rejected the push, so it is still behind the upstream.
41
+ """
42
+
43
+
44
+ class RefusedPushHandling(StrEnum):
45
+ """
46
+ What a fork rejecting the fast-forward's push does to its caller.
47
+ """
48
+
49
+ RAISED = "raised"
50
+ """
51
+ The rejection stops the caller with :class:`GitCommandFailed`.
52
+ """
53
+
54
+ REPORTED = "reported"
55
+ """
56
+ The rejection is reported as :attr:`FastForwardOutcome.PUSH_REFUSED`.
57
+ """
58
+
59
+
60
+ @dataclass(frozen=True)
61
+ class FastForwardReport:
62
+ """
63
+ What the fast-forward did, and to what.
64
+ """
65
+
66
+ outcome: FastForwardOutcome
67
+ """
68
+ What became of the fork's base branch.
69
+ """
70
+
71
+ upstream_reference: str
72
+ """
73
+ The upstream ref the fork's base was compared against.
74
+ """
75
+
76
+ fork_reference: str
77
+ """
78
+ The fork ref that was to be moved.
79
+ """
80
+
81
+ commit: str | None
82
+ """
83
+ The commit the fork's base points at now, absent when the fork has no such branch.
84
+ """
85
+
86
+ explanation: str | None = None
87
+ """
88
+ Why the fork's base was not moved, absent when nothing was refused.
89
+ """
90
+
91
+
92
+ @dataclass(frozen=True)
93
+ class ForkBaseFastForward:
94
+ """
95
+ Moves the fork's copy of a base branch onto a commit the upstream already holds.
96
+
97
+ A move that is not a fast-forward is refused rather than forced - the fork's base is a
98
+ mirror of the upstream trunk, and anything else on it would flow into every branch
99
+ above. Fetching the fork's base never moves ``FETCH_HEAD``.
100
+ """
101
+
102
+ git: GitCommandRunner
103
+ """
104
+ The runner every git command goes through.
105
+ """
106
+
107
+ fork_remote: str
108
+ """
109
+ The remote holding the fork's copy of the base.
110
+ """
111
+
112
+ base_branch: str
113
+ """
114
+ The base branch, by the name the upstream and the fork share.
115
+ """
116
+
117
+ refused_push: RefusedPushHandling
118
+ """
119
+ What the fork rejecting the push does to the caller.
120
+ """
121
+
122
+ @property
123
+ def fork_reference(self) -> str:
124
+ """
125
+ :return: The tracking ref the fork's copy of the base is fetched into.
126
+ """
127
+ return f"{self.fork_remote}/{self.base_branch}"
128
+
129
+ def onto(self, upstream_reference: str) -> FastForwardReport:
130
+ """
131
+ Move the fork's base onto the commit an upstream ref names.
132
+
133
+ :param upstream_reference: The already-fetched upstream ref to move it onto.
134
+ :return: What was done.
135
+ :raises GitCommandFailed: If the fork rejects the push and
136
+ :attr:`refused_push` is :attr:`RefusedPushHandling.RAISED`.
137
+ """
138
+ upstream_commit = self.git.commit_at(upstream_reference)
139
+ self.git.fetch_branch(self.fork_remote, self.base_branch, self.fork_remote)
140
+ fork_commit = self.git.commit_or_none(self.fork_reference)
141
+
142
+ if fork_commit == upstream_commit:
143
+ return self.report(
144
+ FastForwardOutcome.ALREADY_CURRENT, upstream_reference, fork_commit
145
+ )
146
+ if fork_commit is not None and not self.git.contains(
147
+ fork_commit, upstream_commit
148
+ ):
149
+ return self.report(
150
+ FastForwardOutcome.REFUSED_NOT_FAST_FORWARD,
151
+ upstream_reference,
152
+ fork_commit,
153
+ explanation=(
154
+ f"'{self.fork_reference}' is not contained in "
155
+ f"'{upstream_reference}', so moving it would discard commits; "
156
+ f"resolve this by hand rather than forcing"
157
+ ),
158
+ )
159
+ pushed = self.git.push(
160
+ ProposedPush(
161
+ remote=self.fork_remote,
162
+ refspec=f"{upstream_commit}:refs/heads/{self.base_branch}",
163
+ )
164
+ )
165
+ if self.refused_push is RefusedPushHandling.RAISED:
166
+ pushed.raise_if_failed()
167
+ if not pushed.succeeded:
168
+ return self.report(
169
+ FastForwardOutcome.PUSH_REFUSED,
170
+ upstream_reference,
171
+ fork_commit,
172
+ explanation=pushed.error_output,
173
+ )
174
+ self.git.fetch_branch(self.fork_remote, self.base_branch, self.fork_remote)
175
+ return self.report(
176
+ FastForwardOutcome.PUSHED, upstream_reference, upstream_commit
177
+ )
178
+
179
+ def report(
180
+ self,
181
+ outcome: FastForwardOutcome,
182
+ upstream_reference: str,
183
+ commit: str | None,
184
+ explanation: str | None = None,
185
+ ) -> FastForwardReport:
186
+ """
187
+ :param outcome: What became of the fork's base.
188
+ :param upstream_reference: The upstream ref it was compared against.
189
+ :param commit: The commit the fork's base points at now.
190
+ :param explanation: Why it was not moved, if it was not.
191
+ :return: The report, naming this fast-forward's fork ref.
192
+ """
193
+ return FastForwardReport(
194
+ outcome, upstream_reference, self.fork_reference, commit, explanation
195
+ )
196
+
197
+
198
+ def fast_forward(
199
+ configuration: Configuration, git: GitCommandRunner
200
+ ) -> FastForwardReport:
201
+ """
202
+ Fetch the upstream's base, then move the fork's copy of it onto the upstream's tip.
203
+
204
+ This is what closes the pull requests based on that branch whose work has landed:
205
+ GitHub marks one merged the moment its head becomes an ancestor of its base. One based
206
+ on another branch is not closed by it.
207
+
208
+ :param configuration: The resolved configuration.
209
+ :param git: The runner to execute through.
210
+ :return: What was done.
211
+ :raises GitCommandFailed: If the fork rejects the push.
212
+ """
213
+ git.fetch_branch(
214
+ configuration.upstream_location,
215
+ configuration.upstream_base,
216
+ configuration.upstream_remote,
217
+ ).raise_if_failed()
218
+ return ForkBaseFastForward(
219
+ git,
220
+ configuration.fork_remote,
221
+ configuration.upstream_base,
222
+ RefusedPushHandling.RAISED,
223
+ ).onto(f"{configuration.upstream_remote}/{configuration.upstream_base}")