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.
- basstler/maintenance/__init__.py +0 -0
- basstler/maintenance/__main__.py +128 -0
- basstler/maintenance/board.py +113 -0
- basstler/maintenance/check_overview.py +80 -0
- basstler/maintenance/commands.py +595 -0
- basstler/maintenance/default_branch_sync.py +444 -0
- basstler/maintenance/exceptions.py +36 -0
- basstler/maintenance/fast_forward.py +223 -0
- basstler/maintenance/finish_summary.py +515 -0
- basstler/maintenance/fork_pull_request_action.py +38 -0
- basstler/maintenance/landed_closing.py +85 -0
- basstler/maintenance/landed_closing_follow_up.py +85 -0
- basstler/maintenance/promotion.py +248 -0
- basstler/maintenance/promotion_context.py +221 -0
- basstler/maintenance/report.py +304 -0
- basstler/maintenance/restack_procedure.py +279 -0
- basstler/maintenance/restack_steps.py +769 -0
- basstler/maintenance/upstream_pull_request_synchronization.py +189 -0
- basstler/maintenance/upstream_read_route.py +37 -0
- basstler/stack/__init__.py +0 -0
- basstler/stack/__main__.py +377 -0
- basstler/stack/branch_status.py +54 -0
- basstler/stack/checkout.py +416 -0
- basstler/stack/commit_move.py +218 -0
- basstler/stack/exceptions.py +233 -0
- basstler/stack/label_write.py +68 -0
- basstler/stack/merge_probe.py +195 -0
- basstler/stack/model.py +696 -0
- basstler/stack/promotability.py +103 -0
- basstler/stack/promotion_link.py +138 -0
- basstler/stack/report.py +304 -0
- basstler/stack/settings.py +453 -0
- basstler/stack/stack.toml +31 -0
- basstler_stack-4.2.0.dist-info/METADATA +16 -0
- basstler_stack-4.2.0.dist-info/RECORD +38 -0
- basstler_stack-4.2.0.dist-info/WHEEL +4 -0
- basstler_stack-4.2.0.dist-info/licenses/LICENSE +202 -0
- 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}")
|