.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Debian::PkgPerl::GitHub 3pm"
.TH Debian::PkgPerl::GitHub 3pm 2024-03-04 "pkg-perl-tools 0.78" "Debian Perl packaging Tools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Debian::PkgPerl::GitHub \- Help forwarding a bug or a patch to GitHub
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 4
\&    use Debian::PkgPerl::Bug;
\&    use Debian::PkgPerl::Patch;
\&    use Debian::PkgPerl::Message;
\&    use Debian::PkgPerl::GitHub;
\&    
\&    my %params = (
\&        url     => \*(Aqhttps://github.com/foo/bar/issues\*(Aq,
\&        tracker => \*(Aqgithub\*(Aq,
\&        dist    => \*(AqFoo\-Bar\*(Aq,
\&        name    => \*(AqMy Name\*(Aq,
\&        email   => \*(Aqmy.name@example.com\*(Aq,
\&        mailto  => \*(Aqyour.name@example.com\*(Aq,
\&    );
\&    
\&    my %bug_info = Debian::PkgPerl::Bug
\&        \->new( bug => 123 )
\&        \->retrieve_bug_info();
\&    my $bug_msg = Debian::PkgPerl::Message\->new(
\&        %params,
\&        info => \e%bug_info,
\&    );
\&    print Debian::PkgPerl::GitHub\->new(
\&        message => $bug_msg,
\&        ticket  => 456,
\&    )\->forward();
\&    
\&    my %patch_info = Debian::PkgPerl::Patch
\&        \->new( patch => \*(Aqfoo\-bar.patch\*(Aq )
\&        \->retrieve_patch_info();
\&    my $patch_msg = Debian::PkgPerl::Message\->new(
\&        %params,
\&        info => \e%patch_info,
\&    );
\&    print Debian::PkgPerl::GitHub\->new(
\&        message  => $patch_msg,
\&        fallback => 0,
\&    )\->forward();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module exports several helpers that that provide support for
forwarding patches to GitHub as pull requests.
.SH METHODS
.IX Header "METHODS"
.SS new(%params)
.IX Subsection "new(%params)"
\fIParameters:\fR
.IX Subsection "Parameters:"
.IP \(bu 4
message
.Sp
Message to be forwarded to an upstream project.
.IP \(bu 4
ticket
.Sp
Existing issue number to forward the bug to.
.IP \(bu 4
fallback
.Sp
Enables fallback to forwarding a patch as an issue if pull-request
fails for any reason. Default is false.
.PP
\fIEnvironment:\fR
.IX Subsection "Environment:"
.IP \(bu 4
DPT_GITHUB_OAUTH
.Sp
GitHub personal API token. No default.
.IP \(bu 4
DPT_GITHUB_ORGNAME
.Sp
Organization used to fork upstreams. Defaults to \fIpkg-perl-tools\fR.
.IP \(bu 4
DPT_GITHUB_BRANCH
.Sp
Branch name for pull requests. Defaults to \f(CW\*(C`pkg\-perl\-$^T\*(C'\fR.
.IP \(bu 4
DPT_GITHUB_PROTOCOL
.Sp
Protocol used to clone a repository. Defaults to \fIssh\fR.
Accepted protocols: \fIssh\fR, \fIhttps\fR.
.SS \fBfork_exists()\fP
.IX Subsection "fork_exists()"
Checks if any member in the GitHub organization has already forked a repository.
.PP
\fIReturns:\fR
.IX Subsection "Returns:"
.PP
Boolean value.
.SS \fBcreate_fork()\fP
.IX Subsection "create_fork()"
Creates a repository fork by an organization.
.PP
\fIReturns:\fR
.IX Subsection "Returns:"
.PP
The new forked repository.
.SS \fBclone_branch_patch_push()\fP
.IX Subsection "clone_branch_patch_push()"
Clones a repository in a temporary directory, creates a new branch,
applies the patch, commits the change, pushes it and removes the
temporary working copy.
.PP
\fIReturns:\fR
.IX Subsection "Returns:"
.PP
Nothing.
.SS \fBcreate_pull_request()\fP
.IX Subsection "create_pull_request()"
\fIReturns:\fR
.IX Subsection "Returns:"
.PP
Pull request URL on success, nothing otherwise.
.SS \fBforward_patch_as_pull_request()\fP
.IX Subsection "forward_patch_as_pull_request()"
.SS \fBforward_patch_as_ticket()\fP
.IX Subsection "forward_patch_as_ticket()"
Fallback to forwarding a patch as a bug.
.PP
\fIReturns:\fR
.IX Subsection "Returns:"
.PP
Issue URL on success, nothing otherwise.
.SS \fBforward_bug_as_issue()\fP
.IX Subsection "forward_bug_as_issue()"
.SS \fBforward()\fP
.IX Subsection "forward()"
Forward an issue as a pull request or bug.
.SS \fBtest()\fP
.IX Subsection "test()"
Support for off-line testing.
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
.IP "Copyright 2016 Alex Muntada." 4
.IX Item "Copyright 2016 Alex Muntada."
.PD 0
.IP "Copyright 2018 Damyan Ivanov." 4
.IX Item "Copyright 2018 Damyan Ivanov."
.PD
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
.PP
See http://dev.perl.org/licenses/ for more information.