=head1 NAME

pram - (p)ull (r)equests made easy via git (am)!

=head1 DESCRIPTION

The pram utility assists Gentoo developers in merging contributions from the
Gentoo Github repository in the Gentoo git repository.

Let 123 a pull request filed against the official Gentoo Github repository.
pram retrieves this PR from the Github CDN as a patch using the HTTP protocol.
pram then adds the necessary headers to close one or more Gentoo bug reports
but also the PR automatically. pram then opens up the patch with C<$EDITOR> for
you to review it. Eventually, if you deem the contribution good enough and
accept it, pram merges it using the git am command. Git is an essential part of
the backend of pram for merging patches.

At Gentoo we are very opinionated. We are against merge commits. We think they
add unnecessary clutter to the history of a git repository. We want to keep the
history of the Portage tree as linear as possible. For this reason, we leverage
the tools offered by Github to merge contributions as patches without
compromising our standards.

Originally, pram was written to ease the triaging of Gentoo Github PRs and make
it more convenient. Yet, it can be used to merge PRs from virtually any
Github repository. Give it a try!

=head1 SYNOPSIS

pram <pull request number>

 --repository|r <repository> Set repository to fetch PR from.
 --signoff|-s                Pass --signoff option to git am (default if GH repository is gentoo/gentoo).
 --editor|e     <editor>     Set editor to visualise patch in.
 --closes|c     <bug number> Add "Closes: https://bugs.gentoo.org/<bug number>" header to first commit.
 --bug|b        <bug number> Add "Bug: https://bugs.gentoo.org/<bug number>" header to first commit.
 --help|h                    Display help.
 --man|m                     Display a man page.

=head1 EXAMPLE

 # GENTOO DEVELOPERS! Bear in mind that pram fetches pull requests from the
 # Gentoo Github repository by default. You don't need to specify it.

 # Fetch PR 123 and display it in emacs.
 $ pram --editor emacs 123

 # Fetch PR 456 and add a reference to the Gentoo bug report 101010.
 $ pram --bug 101010 456

 # Fetch PR 789 and close the Gentoo bug report 114499.
 $ pram --closes 114499 789

 # Fetch PR 994422 from the Github repository https://github.com/foo/bar.
 $ pram --repository foo/bar 994422

=head1 VERSION

version 0.200000

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2016 by Patrice Clement.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=head1 AUTHOR

Patrice Clement <monsieurp@gentoo.org>

Kent Fredric <kentnl@gentoo.org>

=cut
