NAME

forward - Debian Perl Group forwarding team practices

SYNOPSIS

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

DESCRIPTION

Install

Package Version

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

Development Version

These steps are a quick overview. Find the details in our Git guide.

    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

Forwarding to GitHub

Authentication

You can use 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 dpt through the DPT_GITHUB_OAUTH environment variable. Make sure you define it in dpt configuration.

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 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 admin or a regular member. They can send you an invitation or change your role by using dpt invite-github or the web interface.

GitHub Pull Request

Once everything is set, to create the pull request, run 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 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 --fallback option can be used tell 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).

GitHub Issue

To create a GitHub issue from an existing bug in the Debian BTS, run 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.

Forwarding to CPAN

Authentication

Your PAUSE credentials should be available in $HOME/.pause to be able to access to CPAN Request Tracker API. Otherwise, dpt forward will automatically fall back to email.

CPAN Patch

To send a patch to CPAN Request Tracker for a Perl package you need to run 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 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.

CPAN Bug

To create a CPAN RT issue from an existing bug in the Debian BTS, run 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.

Forwarding by Mail

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

SEE ALSO

AUTHORS

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 /usr/share/common-licenses/GPL and the Artistic License in /usr/share/common-licenses/Artistic.