=head1 NAME

forward - Debian Perl Group forwarding team practices

=head1 SYNOPSIS

    dpt forward 123
    dpt forward debian/patches/foobar.patch

=head1 DESCRIPTION

=head2 Install

=head3 Package Version

    sudo apt install pkg-perl-tools
    echo 'DPT_PACKAGES=$HOME/src/pkg-perl/packages' >> ~/.config/dpt.conf

=head3 Development Version

These steps are a quick overview. Find the details in our
L<Git guide|https://perl-team.pages.debian.net/git.html>.

    cd $HOME
    mkdir -p $HOME/src/pkg-perl/packages
    cd $HOME/src/pkg-perl/packages
    dpt checkout pkg-perl-tools
    echo 'DPT__SCRIPTS=$DPT_PACKAGES/pkg-perl-tools/scripts' >> ~/.config/dpt.conf
    echo 'export PERL5LIB=$DPT_PACKAGES/pkg-perl-tools/lib' >> ~/.config/dpt.conf

=head2 Forwarding to GitHub

=head3 Authentication

You can use C<dpt github-oauth> to get an OAuth2 token or, in case you
have two-factor authentication (2FA) enabled on GitHub, you'll need to
obtain the token from the web interface.

The token is passed to C<dpt> through the C<DPT_GITHUB_OAUTH>
environment variable. Make sure you define it in C<dpt> configuration.

=head3 Organization Membership

The pull request feature for GitHub requires that you belong to an
organization that will be used to share the cloned repositories. The
default organization is named
L<pkg-perl-tools|https://github.com/pkg-perl-tools>.

In order to join the organization you need to ask any of the current
administrators to invite you in, either as an I<admin> or a regular
I<member>. They can send you an invitation or change your role by using
C<dpt invite-github> or the web interface.

=head3 GitHub Pull Request

Once everything is set, to create the pull request,
run C<dpt forward> from the working copy of the package repository
and pass the previously existing patch file as an argument.

You will need to provide a I<subject> that will be used as a summary
for the pull request, and then an editor will open with the comments
pre-filled for you to review before sending them upstream. If all the
comments are removed, the pull request will be aborted.

The C<--fallback> option can be used tell C<dpt forward> to open an
issue instead when something goes wrong while making the pull request,
which can happen when a patch doesn't apply, e.g. if the git repo differs
from the contents of the released tarball on the CPAN (which the
patch was created against).

=head3 GitHub Issue

To create a GitHub issue from an existing bug in the Debian BTS,
run C<dpt forward> and pass the bug number as an
argument. You will have the chance to review the contents of the bug
report before sending it upstream.

=head2 Forwarding to CPAN

=head3 Authentication

Your L<PAUSE|https://pause.perl.org/> credentials should be available
in F<$HOME/.pause> to be able to access to CPAN Request Tracker API.
Otherwise, C<dpt forward> will automatically fall back to email.

=head3 CPAN Patch

To send a patch to CPAN Request Tracker for a Perl package you need to
run C<dpt forward> from the working copy of the package repository and
pass the previously existing patch file as an argument.

You will need to provide a I<subject> that will be used as a summary
for the pull request, and then an editor will open with the comments
pre-filled for you to review before sending them upstream. If all the
comments are removed, the pull request will be aborted.

=head3 CPAN Bug

To create a CPAN RT issue from an existing bug in the Debian BTS,
run C<dpt forward> and pass the bug number as an
argument. You will have the chance to review the contents of the bug
report before sending it upstream.

=head2 Forwarding by Mail

In some cases, people prefer to be notified by mail instead of any other
bug tracking system. You can use C<--use-mail> and C<--mailto> options
in C<dpt forward> to achieve that.

=head1 SEE ALSO

=over

=item * L<dpt-config(5)>

=item * L<dpt-github-oauth(1)>

=item * L<dpt-invite-github(1)>

=item * L<dpt-forward(1)>

=back

=head1 AUTHORS

=over

=item * Alex Muntada

=back

=head1 LICENSE

Copyright (c) 2016, 2017 by the individual authors and contributors
noted above. All rights reserved. This document is free software;
you may redistribute it and/or modify it under the same terms as
Perl itself.

Perl is distributed under your choice of the GNU General Public
License or the Artistic License. On Debian GNU/Linux systems,
the complete text of the GNU General Public License can be found
in C</usr/share/common-licenses/GPL> and the Artistic License in
C</usr/share/common-licenses/Artistic>.