1
# Copyright (C) 2018-2019 Breezy Developers
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
# GNU General Public License for more details.
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17
"""Helper functions for proposing merges."""
27
class NoSuchProject(errors.BzrError):
29
_fmt = "Project does not exist: %(project)s."
31
def __init__(self, project):
32
errors.BzrError.__init__(self)
33
self.project = project
36
class MergeProposalExists(errors.BzrError):
38
_fmt = "A merge proposal already exists: %(url)s."
40
def __init__(self, url):
41
errors.BzrError.__init__(self)
45
class UnsupportedHoster(errors.BzrError):
47
_fmt = "No supported hoster for %(branch)s."
49
def __init__(self, branch):
50
errors.BzrError.__init__(self)
54
class ReopenFailed(errors.BzrError):
56
_fmt = "Reopening the merge proposal failed: %(error)s."
59
class ProposeMergeHooks(hooks.Hooks):
60
"""Hooks for proposing a merge on Launchpad."""
63
hooks.Hooks.__init__(self, __name__, "Proposer.hooks")
66
"Return the prerequisite branch for proposing as merge.", (3, 0))
68
'merge_proposal_body',
69
"Return an initial body for the merge proposal message.", (3, 0))
72
class LabelsUnsupported(errors.BzrError):
73
"""Labels not supported by this hoster."""
75
_fmt = "Labels are not supported by %(hoster)r."
77
def __init__(self, hoster):
78
errors.BzrError.__init__(self)
82
class PrerequisiteBranchUnsupported(errors.BzrError):
83
"""Prerequisite branch not supported by this hoster."""
85
def __init__(self, hoster):
86
errors.BzrError.__init__(self)
90
class HosterLoginRequired(errors.BzrError):
91
"""Action requires hoster login credentials."""
93
_fmt = "Action requires credentials for hosting site %(hoster)r."""
95
def __init__(self, hoster):
96
errors.BzrError.__init__(self)
100
class MergeProposal(object):
103
:ivar url: URL for the merge proposal
106
def __init__(self, url=None):
109
def get_description(self):
110
"""Get the description of the merge proposal."""
111
raise NotImplementedError(self.get_description)
113
def set_description(self, description):
114
"""Set the description of the merge proposal."""
115
raise NotImplementedError(self.set_description)
117
def get_commit_message(self):
118
"""Get the proposed commit message."""
119
raise NotImplementedError(self.get_commit_message)
121
def set_commit_message(self, commit_message):
122
"""Set the propose commit message."""
123
raise NotImplementedError(self.set_commit_message)
125
def get_source_branch_url(self):
126
"""Return the source branch."""
127
raise NotImplementedError(self.get_source_branch_url)
129
def get_target_branch_url(self):
130
"""Return the target branch."""
131
raise NotImplementedError(self.get_target_branch_url)
133
def get_source_project(self):
134
raise NotImplementedError(self.get_source_project)
136
def get_target_project(self):
137
raise NotImplementedError(self.get_target_project)
140
"""Close the merge proposal (without merging it)."""
141
raise NotImplementedError(self.close)
144
"""Check whether this merge proposal has been merged."""
145
raise NotImplementedError(self.is_merged)
148
"""Check whether this merge proposal is closed
150
This can either mean that it is merged or rejected.
152
raise NotImplementedError(self.is_closed)
154
def merge(self, commit_message=None):
155
"""Merge this merge proposal."""
156
raise NotImplementedError(self.merge)
158
def can_be_merged(self):
159
"""Can this merge proposal be merged?
161
The answer to this can be no if e.g. it has conflics.
163
raise NotImplementedError(self.can_be_merged)
165
def get_merged_by(self):
166
"""If this proposal was merged, who merged it.
168
raise NotImplementedError(self.get_merged_by)
170
def get_merged_at(self):
171
"""If this proposal was merged, when it was merged.
173
raise NotImplementedError(self.get_merged_at)
176
class MergeProposalBuilder(object):
177
"""Merge proposal creator.
179
:param source_branch: Branch to propose for merging
180
:param target_branch: Target branch
183
hooks = ProposeMergeHooks()
185
def __init__(self, source_branch, target_branch):
186
self.source_branch = source_branch
187
self.target_branch = target_branch
189
def get_initial_body(self):
190
"""Get a body for the proposal for the user to modify.
192
:return: a str or None.
194
raise NotImplementedError(self.get_initial_body)
196
def get_infotext(self):
197
"""Determine the initial comment for the merge proposal.
199
raise NotImplementedError(self.get_infotext)
201
def create_proposal(self, description, reviewers=None, labels=None,
202
prerequisite_branch=None, commit_message=None,
203
work_in_progress=False, allow_collaboration=False):
204
"""Create a proposal to merge a branch for merging.
206
:param description: Description for the merge proposal
207
:param reviewers: Optional list of people to ask reviews from
208
:param labels: Labels to attach to the proposal
209
:param prerequisite_branch: Optional prerequisite branch
210
:param commit_message: Optional commit message
211
:param work_in_progress:
212
Whether this merge proposal is still a work-in-progress
213
:param allow_collaboration:
214
Whether to allow changes to the branch from the target branch
216
:return: A `MergeProposal` object
218
raise NotImplementedError(self.create_proposal)
221
class Hoster(object):
222
"""A hosting site manager.
225
# Does this hoster support arbitrary labels being attached to merge
227
supports_merge_proposal_labels = None
229
# Does this hoster support suggesting a commit message in the
231
supports_merge_proposal_commit_message = None
233
# The base_url that would be visible to users. I.e. https://github.com/
234
# rather than https://api.github.com/
237
# The syntax to use for formatting merge proposal descriptions.
238
# Common values: 'plain', 'markdown'
239
merge_proposal_description_format = None
241
# Does this hoster support the allow_collaboration flag?
242
supports_allow_collaboration = False
244
def publish_derived(self, new_branch, base_branch, name, project=None,
245
owner=None, revision_id=None, overwrite=False,
246
allow_lossy=True, tag_selector=None):
247
"""Publish a branch to the site, derived from base_branch.
249
:param base_branch: branch to derive the new branch from
250
:param new_branch: branch to publish
251
:return: resulting branch, public URL
252
:raise HosterLoginRequired: Action requires a hoster login, but none is
255
raise NotImplementedError(self.publish)
257
def get_derived_branch(self, base_branch, name, project=None, owner=None):
258
"""Get a derived branch ('a fork').
260
raise NotImplementedError(self.get_derived_branch)
262
def get_push_url(self, branch):
263
"""Get the push URL for a branch."""
264
raise NotImplementedError(self.get_push_url)
266
def get_proposer(self, source_branch, target_branch):
267
"""Get a merge proposal creator.
269
:note: source_branch does not have to be hosted by the hoster.
271
:param source_branch: Source branch
272
:param target_branch: Target branch
273
:return: A MergeProposalBuilder object
275
raise NotImplementedError(self.get_proposer)
277
def iter_proposals(self, source_branch, target_branch, status='open'):
278
"""Get the merge proposals for a specified branch tuple.
280
:param source_branch: Source branch
281
:param target_branch: Target branch
282
:param status: Status of proposals to iterate over
283
:return: Iterate over MergeProposal object
285
raise NotImplementedError(self.iter_proposals)
287
def get_proposal_by_url(self, url):
288
"""Retrieve a branch proposal by URL.
290
:param url: Merge proposal URL.
291
:return: MergeProposal object
292
:raise UnsupportedHoster: Hoster does not support this URL
294
raise NotImplementedError(self.get_proposal_by_url)
296
def hosts(self, branch):
297
"""Return true if this hoster hosts given branch."""
298
raise NotImplementedError(self.hosts)
301
def probe_from_branch(cls, branch):
302
"""Create a Hoster object if this hoster knows about a branch."""
303
url = urlutils.strip_segment_parameters(branch.user_url)
304
return cls.probe_from_url(
305
url, possible_transports=[branch.control_transport])
308
def probe_from_url(cls, url, possible_hosters=None):
309
"""Create a Hoster object if this hoster knows about a URL."""
310
raise NotImplementedError(cls.probe_from_url)
312
def iter_my_proposals(self, status='open'):
313
"""Iterate over the proposals created by the currently logged in user.
315
:param status: Only yield proposals with this status
316
(one of: 'open', 'closed', 'merged', 'all')
317
:return: Iterator over MergeProposal objects
318
:raise HosterLoginRequired: Action requires a hoster login, but none is
321
raise NotImplementedError(self.iter_my_proposals)
323
def iter_my_forks(self):
324
"""Iterate over the currently logged in users' forks.
326
:return: Iterator over project_name
328
raise NotImplementedError(self.iter_my_forks)
330
def delete_project(self, name):
333
raise NotImplementedError(self.delete_project)
336
def iter_instances(cls):
337
"""Iterate instances.
339
:return: Hoster instances
341
raise NotImplementedError(cls.iter_instances)
344
def determine_title(description):
345
"""Determine the title for a merge proposal based on full description."""
346
return description.splitlines()[0].split('.')[0]
349
def get_hoster(branch, possible_hosters=None):
350
"""Find the hoster for a branch.
352
:param branch: Branch to find hoster for
353
:param possible_hosters: Optional list of hosters to reuse
354
:raise UnsupportedHoster: if there is no hoster that supports `branch`
355
:return: A `Hoster` object
358
for hoster in possible_hosters:
359
if hoster.hosts(branch):
361
for name, hoster_cls in hosters.items():
363
hoster = hoster_cls.probe_from_branch(branch)
364
except UnsupportedHoster:
367
if possible_hosters is not None:
368
possible_hosters.append(hoster)
370
raise UnsupportedHoster(branch)
373
def get_proposal_by_url(url):
374
"""Get the proposal object associated with a URL.
376
:param url: URL of the proposal
377
:raise UnsupportedHoster: if there is no hoster that supports the URL
378
:return: A `MergeProposal` object
380
for name, hoster_cls in hosters.items():
381
for instance in hoster_cls.iter_instances():
383
return instance.get_proposal_by_url(url)
384
except UnsupportedHoster:
386
raise UnsupportedHoster(url)
389
hosters = registry.Registry()
added
removed
breezy/propose.py
