'\" t
.\"     Title: how-can-i-help
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 01/24/2017
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "HOW\-CAN\-I\-HELP" "1" "01/24/2017" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
how-can-i-help \- show opportunities for contributing to Debian
.SH "SYNOPSIS"
.sp
\fBhow\-can\-i\-help\fR [\fI\-haoqs\fR] [\fI\-\-help\fR] [\fI\-\-all\fR] [\fI\-\-old\fR] [\fI\-\-quiet\fR] [\fI\-\-show <type>\&...\fR]
.SH "DESCRIPTION"
.sp
\fBhow\-can\-i\-help\fR hooks into APT to list opportunities for contributions to Debian (orphaned packages, bugs tagged \fInewcomer\fR) for packages installed locally, after each APT invocation\&. It can also be invoked directly, and then lists all opportunities for contribution (not just the new ones)\&.
.SH "OPTIONS"
.sp
Options must come before the other command line arguments\&.
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Show some help\&.
.RE
.PP
\fB\-a\fR, \fB\-\-all\fR
.RS 4
Show new opportunities for contribution to all available Debian packages\&.
.RE
.PP
\fB\-o\fR, \fB\-\-old\fR
.RS 4
Show opportunities that were already shown before (will also show the new ones)\&.
.RE
.PP
\fB\-q\fR, \fB\-\-quiet\fR
.RS 4
Do not display header and footer\&.
.RE
.PP
\fB\-j\fR, \fB\-\-json\fR
.RS 4
Display output in JSON format\&.
.RE
.PP
\fB\-p\fR, \fB\-\-apt\fR
.RS 4
Always exit with code 0\&. By default run by apt hook to prevent apt failures\&.
.RE
.PP
\fB\-s <type>\&...\fR, \fB\-\-show <type>\&...\fR
.RS 4
Show only specific types of opportunities\&. Provided types have to be separated by commas\&.
.RE
.SH "PROXY SUPPORT"
.sp
\fBhow\-can\-i\-help\fR uses the HTTP_PROXY (or http_proxy) environment variable as HTTP proxy configuration\&.
.SH "RUNNING ON REGULAR BASIS"
.sp
You can run \fBhow\-can\-i\-help\fR in a cron job as a normal user so that you receive a mail when new things are reported\&. To receive only mails when new contributions are reported, use the \fI\-q\fR flag\&.
.sp
Crontab example:
.sp
.if n \{\
.RS 4
.\}
.nf
0 8 * * * how\-can\-i\-help \-q
.fi
.if n \{\
.RE
.\}
.SH "DISPLAY OUTPUT IN JSON FORMAT"
.sp
\fBhow\-can\-i\-help\fR can be configured to provide machine readable JSON output\&. When running in this mode, only error messages and JSON output will be produced\&. If there are no packages that would be shown, no output will be produced\&. Elements in the JSON output are not sorted\&. All the other options can be used alongside the \fI\-\-json\fR option\&.
.sp
Simple example:
.sp
.if n \{\
.RS 4
.\}
.nf
how\-can\-i\-help \-\-json \-\-show testing\-autorm
.fi
.if n \{\
.RE
.\}
.SH "EXIT CODES"
.sp
When run by apt hook, \fBhow\-can\-i\-help\fR will always exit with code 0, even if an error occurred\&. When \fBhow\-can\-i\-help\fR is called without \fI\-\-apt\fR option, import and command line parsing errors will still exit with code 0, but all the other errors will return appropriate exit codes\&. Regardless of the \fI\-\-apt\fR option, all error messages will be displayed normally\&.
.SH "SHOW ONLY SPECIFIC TYPES OF OPPORTUNITIES"
.sp
\fBhow\-can\-i\-help\fR can be configured to show only specific types of opportunities\&. You only need to run it with \-\-show option followed by a single space and then a list of types\&. Types have to be separated only by commas\&.
.sp
Simple example:
.sp
.if n \{\
.RS 4
.\}
.nf
how\-can\-i\-help \-\-show newcomer,RFH
.fi
.if n \{\
.RE
.\}
.sp
Example showing newcomer opportunities (also the ones that were already shown before):
.sp
.if n \{\
.RS 4
.\}
.nf
how\-can\-i\-help \-\-old \-\-show newcomer
.fi
.if n \{\
.RE
.\}
.sp
The following types can be used: wnpp, newcomer, help, no\-testing, testing\-autorm, rfs
.sp
Specific WNPP types: O, RFA, RFH, ITA
.sp
And special types: pseudo\-package
.SH "IGNORE SELECTED TYPES OF OPPORTUNITIES"
.sp
\fBhow\-can\-i\-help\fR can also ignore selected types of opportunities\&. These are listed in ~/\&.config/how\-can\-i\-help/ignored separated by whitespaces or newlines\&.
.sp
Allowed types: wnpp, newcomer, help, no\-testing, testing\-autorm, rfs
.sp
Allowed WNPP types: O, RFA, RFH, ITA
.sp
Allowed special types: pseudo\-package
.sp
Running with \fI\-\-show\fR option will override "ignored types" configuration\&.
.SH "TYPES OF OPPORTUNITIES"
.sp
The following acronyms are used to describe the supported types:
.sp
\fBwnpp\fR Work\-Needing and Prospective Packages\&.
.sp
\fBnewcomer\fR Bugs tagged with the \fInewcomer\fR tag\&. Those bugs were formerly tagged with the now deprecated \fIgift\fR tag\&.
.sp
\fBhelp\fR Bugs tagged with the \fIhelp\fR tag\&.
.sp
\fBno\-testing\fR Packages removed from Debian \fItesting\fR\&.
.sp
\fBtesting\-autorm\fR Packages going to be removed from Debian \fItesting\fR\&.
.sp
\fBrfs\fR Request For Sponsorship\&.
.sp
\fBO\fR Orphaned\&.
.sp
\fBRFA\fR Request For Adoption\&.
.sp
\fBRFH\fR Request For Help\&.
.sp
\fBITA\fR Intent To Adopt\&.
.sp
\fBpseudo\-package\fR Newcomer bugs affecting Debian infrastructure (general Debian services)\&. Those pseudo\-packages cannot be installed\&.
.SH "ADDITIONAL PACKAGES"
.sp
\fBhow\-can\-i\-help\fR can also monitor packages not installed locally\&. These are listed in ~/\&.config/how\-can\-i\-help/packages separated by whitespaces or newlines\&.
.sp
For example one can monitor all package from a server as follow:
.sp
.if n \{\
.RS 4
.\}
.nf
# ssh myserver dpkg \-l | tail \-n+6 | awk \*(Aq{ print $2 }\*(Aq \e
    >> ~/\&.config/how\-can\-i\-help/packages
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
https://wiki\&.debian\&.org/how\-can\-i\-help
.sp
https://wiki\&.debian\&.org/qa\&.debian\&.org/GiftTag
.sp
https://www\&.debian\&.org/devel/wnpp
.SH "AUTHORS"
.sp
Tomasz Nitecki (tnnn@tnnn\&.pl)
.sp
Lucas Nussbaum (lucas@debian\&.org)
.SH "DATE"
.sp
2016\-03\-03