.TH sponsor\-patch "1" "September 21 2010" "ubuntu-dev-tools"
.SH NAME
sponsor\-patch \- Prepare, test\-build, and sponsor an upload.

.SH SYNOPSIS
.B sponsor\-patch \fR[\fIoptions\fR] \fIbug
.br
.B sponsor\-patch \-h

.SH DESCRIPTION
\fBsponsor\-patch\fR downloads the patch or Bazaar branch linked to an
Ubuntu bug, applies it, generates a review diff, (optionally) test
builds it, runs
.BR lintian (1)
and, after review and confirmation, can upload it.

\fBsponsor\-patch\fR can be used for sponsoring patches, syncs and
merges from Debian, SRUs, and creating debdiffs from patches.
If \fIbug\fR has multiple patches or branches linked, it will prompt the
user to select one.
The same applies to bug tasks.
If the attached patch is not a debdiff,
.BR edit-patch (1)
is used to apply it.

.nr step 1 1
Some obvious checks are performed, in particular:
.IP \n[step]. 4
.BR update\-maintainer (1)
is run on the source package to ensure that the \fBMaintainer\fR field
meets the Ubuntu policy.
.IP \n+[step].
The version number must be greater than the current version in the
archive.
The \fBchanges\fR file is also correctly generated to list all changes
since the current version in the archive.
.IP \n+[step].
The changelog must automatically close the sponsorship bug.
.IP \n+[step].
The changelog target must be valid.
.IP \n+[step].
The changelog timestamp is touched.

.PP
Should any checks (or the build) fail, the user has an option to edit
the patched source and try building it again.
.PP
Unless a working directory is specified, the sources and patches will be
downloaded into a temporary directory in \fB/tmp\fR, which is removed once the
script finishes running.
The output of the build tool will be placed in \fIworkdir\fR/\fBbuildresult/\fR.

.PP
One of \fB\-\-upload\fR, \fB\-\-workdir\fR, or \fB--sponsor\fR must be
specified.

.SH OPTIONS
.TP
.BR \-b ", " \-\-build
Build the package with the specified builder. Note for \fBpbuilder\fR(8) and
\fBcowbuilder\fR(8) users:
This assumes the common configuration, where the \fBARCH\fR and \fBDIST\fR
environment is read by \fBpbuilderrc\fR(5) to select the correct base image.
.TP
.B \-B \fIBUILDER\fR, \fB\-\-builder\fR=\fIBUILDER
Use the specify builder to build the package.
Supported are \fBcowbuilder\fR(8), \fBcowbuilder-dist\fR(1), \fBpbuilder\fR(8),
\fBpbuilder-dist\fR(1), and \fBsbuild\fR(1).
The default is \fBpbuilder\fR(8).
.TP
.BR \-e ", " \-\-edit
Launch a sub-shell to allow editing of the patched source before
building.
.TP
.BR \-h ", " \-\-help
Display a help message and exit.
.TP
.B \-k \fIKEY\fR, \fB\-\-key\fR=\fIKEY
Specify a key ID for signing the upload.
.TP
.B \-l \fIINSTANCE\fR, \fB\-\-lpinstance\fR=\fIINSTANCE\fR
Use the specified instance of Launchpad (e.g. "staging"), instead of
the default of "production".
.TP
.B \-\-no\-conf
Do not read any configuration files, or configuration from environment
variables.
.TP
.BR \-s ", " \-\-sponsor
Shortcut for sponsored uploads. Equivalent to \fB\-b \-u ubuntu\fR.
.TP
.B \-u \fIDEST\fR, \fB\-\-upload\fR=\fIDEST
Upload to \fIDEST\fR with \fBdput\fR(1) (after confirmation).
.TP
.BR \-U ", " \-\-update
Update the build environment before attempting to build.
.TP
.BR \-v ", " \-\-verbose
Print more information.
.TP
.B \-w \fIDIR\fR, \fB\-\-workdir\fR=\fIDIR
Use the specified working directory, creating it if necessary.
If \fIWORKDIR\fR is not specified, a temporary directory is created, which is
deleted before \fIsponsor-patch\fR exits.

.SH ENVIRONMENT
All of the \fBCONFIGURATION VARIABLES\fR below are also supported as environment
variables.
Variables in the environment take precedence to those in configuration files.

.SH CONFIGURATION VARIABLES
The following variables can be set in the environment or in
.BR ubuntu\-dev\-tools (5)
configuration files.
In each case, the script\-specific variable takes precedence over the
package\-wide variable.
.TP
.BR SPONSOR_PATCH_BUILDER ", " UBUNTUTOOLS_BUILDER
The default value for \fB\-\-builder\fR.
.TP
.BR SPONSOR_PATCH_LPINSTANCE ", " UBUNTUTOOLS_LPINSTANCE
The default value for \fB--lpinstance\fR.
.TP
.BR SPONSOR_PATCH_UPDATE_BUILDER ", " UBUNTUTOOLS_UPDATE_BUILDER
The default value for \fB--update\fR.
.TP
.BR SPONSOR_PATCH_WORKDIR ", " UBUNTUTOOLS_WORKDIR
The default value for \fB--workdir\fR.
.TP
.BR SPONSOR_PATCH_KEYID ", " UBUNTUTOOLS_KEYID
The default value for \fB--key\fR.

.SH EXAMPLES
Test-building and sponsoring an upload of bug \fB1234\fR:
.IP
.nf
.B sponsor\-patch -s 1234
.fi

.PP
Performing a test build of bug \fB1234\fR in your PPA:
.IP
.nf
.B sponsor\-patch -u ppa:\fIuser\fR/\fIppa\fB 1234
.fi

.SH SEE ALSO
.BR bzr (1),
.BR debchange (1),
.BR debdiff (1),
.BR dput (1),
.BR edit-patch (1),
.BR lintian (1),
.BR cowbuilder (8),
.BR cowbuilder-dist (1),
.BR pbuilder (8),
.BR pbuilder-dist (1),
.BR sbuild (1),
.BR ubuntu\-dev\-tools (5),
.BR update\-maintainer (1)

.SH AUTHORS
\fBsponsor\-patch\fR was written by Benjamin Drung <bdrung@ubuntu.com>,
and this manual page was written by Stefano Rivera <stefanor@ubuntu.com>.
.PP
Both are released under the terms of the ISC License.