diff options
Diffstat (limited to 'dist-tools/shipper/shipper.xml')
| -rw-r--r-- | dist-tools/shipper/shipper.xml | 752 |
1 files changed, 0 insertions, 752 deletions
diff --git a/dist-tools/shipper/shipper.xml b/dist-tools/shipper/shipper.xml deleted file mode 100644 index 765f0f54..00000000 --- a/dist-tools/shipper/shipper.xml +++ /dev/null @@ -1,752 +0,0 @@ -<!DOCTYPE refentry PUBLIC - "-//OASIS//DTD DocBook XML V4.1.2//EN" - "docbook/docbookx.dtd"> -<refentry id='shipper.1'> -<refmeta> -<refentrytitle>shipper</refentrytitle> -<manvolnum>1</manvolnum> -</refmeta> -<refnamediv id='name'> -<refname> shipper</refname> -<refpurpose>automatic drop-shipping of project releases</refpurpose> -</refnamediv> -<refsynopsisdiv id='synopsis'> - -<cmdsynopsis> - <command>shipper</command> - <arg choice='opt'>-h</arg> - <arg choice='opt'>-n</arg> - <arg choice='opt'>-N</arg> - <arg choice='opt'>-f</arg> - <arg choice='opt'>-v</arg> -</cmdsynopsis> -<cmdsynopsis> - <command>buildrpms</command> - <arg choice='req'><replaceable>tarball</replaceable></arg> -</cmdsynopsis> -</refsynopsisdiv> - -<refsect1><title>Description</title> - -<para><application>shipper</application> is a tool for shipping -project releases. Its job is to make it possible for you to run the -command <command>shipper</command> in the top-level directory of a -project and have a release be properly exported to all the places that -you normally deliver it — your personal website, Linux source -code archive sites, and distribution submission queues. A second goal -is to arrange your shipping process in such a way that metadata like -your project version only have to be kept in one place and modified -once per release. The overall goal is to reduce the friction cost -of shipping releases to as near zero as possible.</para> - -<para><application>buildrpms</application> is a helper script that -builds source and binary RPMs from a specified tarball with a -BuildRoot field. <application>shipper</application> also calls -<citerefentry> -<refentrytitle>rpm2lsm</refentrytitle> -<manvolnum>1</manvolnum></citerefentry> to do part of its work.</para> - -<para>As much as possible, <application>shipper</application> tries to -deduce what it should do rather than requiring you to tell it. In -order to do this, it relies on your project obeying standard GNU-like -naming conventions. It also relies on being able to mine project -metadata out of a package specfile. (Presently the only variety of -package specfile supported is an RPM spec; this may change in the future, -when we fully support shipping Debian packages.)</para> - -<para>In normal use, you need set only one configuration variable, -which is the list of private destinations to ship to. You may also -want to add some magic <quote>Keywords</quote> comments to your -project specfiles. Once you have <application>shipper</application> -up and running, you can experiment with more advanced features -such as having the program generate project web pages for you.</para> -</refsect1> - -<refsect1><title>Theory of Operation</title> - -<para><application>shipper</application> pushes -<emphasis>deliverables</emphasis> out to -<emphasis>destinations</emphasis>. Deliverables include: source tarballs, -source zip archives, source RPMs, binary RPMs, ChangeLog files, README -files, LSM files, and various other project metadata files. Destinations -include both <emphasis>private destinations</emphasis> like websites, FTP -archive sites and mailing lists, and <emphasis>public -channels</emphasis> like ibiblio, freshmeat.net, and the submission -queues for various well-known operating-system distributions. The -shipper framework is extensible and it is relatively easy to add new -channel types and new deliverables; in the future, we hope to support -(for example) Debian packages as deliverables and SourceForge as a -channel.</para> - -<para><application>shipper</application>'s first step is to find the -project name and version, then to check that the minimum set of files that -<application>shipper</application> requires to continue is in place. -To start with, <application>shipper</application> needs a source -tarball and a specfile. Once it knows those are in place, it -can extract various pieces of information it will need to do its -real work. It also reads in a handful of configuration variables. -The -N (nobuild) option causes it to dump all configuration values and -stop there.</para> - -<para>The first real work that gets done is finding or building local -deliverables. These are either <emphasis>generated -deliverables</emphasis> (like RPMs) that can be rebuilt automatically, -or or <emphasis>stock deliverables</emphasis> (like a README file) -that have to be changed by hand. <application>shipper</application> -rebuilds any generated deliverable that doesn't exist when it starts -up. Building local deliverables is separated from uploading because -it means that you can stop and inspect what you're going to ship -before committing to an upload.</para> - -<para>The -n (noupload) option stops before uploading, leaving all -local deliverables in place but displaying the exact upload commands -that would have been used to ship them. The -f (force) option forces -a rebuild of all generated deliverables, even those that already -exist. The command <command>shipper -f -n</command> will show you -exactly what <application>shipper</application> would do for a real -upload.</para> - -<para>Once all local deliverables have been built, -<application>shipper</application> can begin uploading files and -posting announcements. It does private destinations first, then public -channels. This means, for example, that if you give -<application>shipper</application> your personal website as a destination, the -website will get updated each time <emphasis>before</emphasis> -any submissions or announcements are sent to public sites like -ibiblio.org or freshmeat.net.</para> - -<para>When uploads are complete, <application>shipper</application> -cleans up after itself by deleting any deliverables it created for -this run. Deliverables that were found and up to date are not -removed.</para> - -<para>Finally, note that <application>shipper</application> makes one -important assumption about the structure of your website(s). Beneath -each directory in your <varname>destinations</varname> list, there -will be one subdirectory for each project, with the directory leaf -name being the same as the project. Thus, for example, if you have -three projects named ruby, diamond and sapphire, and your personal -site is at <filename>gemstones.net:/public/www/precious/</filename>, -<application>shipper</application> will expect to be able to drop -deliverables in three directories -<filename>gemstones.net:/public/www/precious/ruby</filename>, -<filename>gemstones.net:/public/www/precious/diamond/</filename>, and -<filename>gemstones.net:/public/www/precious/sapphire/</filename>. -Note that <application>shipper</application> will not create these -project directories for you if they're missing; this is deliberate, so -that uploads to sites that are not prepared for them will fail -noisily.</para> - -</refsect1> - -<refsect1><title>How Shipper Deduces What To Do</title> - -<para>The behavior of shipper depends on a handful of internal -variables. Some of these variables have defaults computed at startup -time. All can be set or overridden in the per-user -<filename>~/.shipper</filename> file, and overridden in any -per-project <filename>.shipper</filename> file. Both files are Python -code and the syntax of variable settings is Python's.</para> - -<para>If a variable is set in a config file, that value is locked in -(except for the <varname>destinations</varname> variable which can be -appended to from a specfile, see below) Variables that are -<emphasis>not</emphasis> set in a config file may be set by the values -of fields in your project specfile.</para> - -<para>For basic use, it is only necessary to set one such variable: -<varname>destinations</varname>, the list of destinations to ship to. -Normally you'll set this globally, pointing all your projects at your -main distribution website, in your <filename>~/.shipper</filename> -file; it is also possible to add destinations on a per-project basis -by giving a comma-separated list in a #Destinations: comment in the -specfile. You can set the variable in a per-project -<filename>.shipper</filename> to ignore your global destination -list.</para> - -<para>The first thing shipper looks for is a specfile in the -current directory; there must be exactly one. It extracts the project -name from the Name field. Next step is to find the project version -(the variable <varname>package</varname>). This is extracted from the -specfile, or by looking for a makefile macro with a name -beginning with VERS; if the value of that macro is a shell command -wrapped in $(shell ...), it is executed and the output is captured to -yield the version. If both versions are present, they are -consistency-checked.</para> - -<para><application>shipper</application> gets most of the rest of the -data it uses to decide what to do from headers in the specfile. -The following table lists all the variables and their corresponding -specfile fields. <application>shipper</application> uses the RPM spec -file fields: the Debian entries are informational only.</para> - -<informaltable> -<tgroup cols="4"> -<thead> -<row> -<entry>Variable</entry> -<entry>RPM specfile field</entry> -<entry>Debian specfile field</entry> -<entry>Meaning</entry> -</row> -</thead> -<tbody> -<row> -<entry><varname>destinations</varname></entry> -<entry>#Destinations:</entry> -<entry>XBS-Destinations:</entry> -<entry> -<para>A list of remote directories to ship to using -<citerefentry> -<refentrytitle>scp</refentrytitle> <manvolnum>1</manvolnum> -</citerefentry>. Each location is a place to drop deliverables: -either a [user@]site:path destination that -<citerefentry> -<refentrytitle>scp</refentrytitle> <manvolnum>1</manvolnum> -</citerefentry> can use, or an FTP url that -<citerefentry> -<refentrytitle>lftp</refentrytitle> <manvolnum>1</manvolnum> -</citerefentry> -can use. Note that actual project directories are computed by -appending the value of <varname>package</varname> to -the destination you're shipping to.</para> - -<para><emphasis role='bold'>There is no default.</emphasis>. If you -do not set this variable, <application>shipper</application> will -ship only to public channels.</para> -</entry> -</row> -<row> -<entry><varname>channels</varname></entry> -<entry align='center'>-</entry> -<entry align='center'>-</entry> -<entry> -<para>The list of public channels to be shipped to after the private -channels in the <varname>destination</varname> list. You can disable -one or more of these in a config file by calling the function -<function>disable()</function>; for example with -<command>disable('freshmeat')</command>.</para> -</entry> -</row> -<row> -<entry><varname>whoami</varname></entry> -<entry align='center'>-</entry> -<entry align='center'>-</entry> -<entry> -<para>A plausible email address for the user. If not specified in the -config file, it's generated from -<envar>$USERNAME</envar> and <envar>$HOSTNAME</envar>.</para> -</entry> -</row> -<row> -<entry><varname>date</varname></entry> -<entry align='center'>-</entry> -<entry align='center'>-</entry> -<entry> -<para>The program's startup time. This can be used in the web page and -email announcement templates.</para> - -<para>You can use the Python function time.strftime("...") in your -<filename>~/.shipper</filename> file to format this date to your -taste. If you don't set this in the config file, the program will -set it for you.</para> -</entry> -</row> -<row> -<entry><varname>indextemplate</varname></entry> -<entry align='center'>-</entry> -<entry align='center'>-</entry> -<entry> -<para>Template HTML from which to generate index.html for shipping. There is a -default which generates a very simple page containing a title, a -date, and a table listing downloadable resources. This is used when -shipping to a web directory, if no index page exists when shipper -is run.</para> -</entry> -</row> -<row> -<entry><varname>mailtemplate</varname></entry> -<entry align='center'>-</entry> -<entry align='center'>-</entry> -<entry> -<para>Template text from which to generate the file ANNOUNCE.EMAIL to be -shipped to destinations that are mailto URLs. There is a default which -generates a very simple email containing a subject, a pointer to the -project web page, and the last entry in the project changelog.</para> -</entry> -</row> -<row> -<entry><varname>package</varname></entry> -<entry>Name:</entry> -<entry>Package:</entry> -<entry> -<para>Project name, used to generate the stem part of the names of RPMs and -other deliverables that <application>shipper</application> -builds. If the specfile is a Debian control file, the Debian-specific -part of the version number (after the dash) is removed.</para> -</entry> -</row> -<row> -<entry><varname>version</varname></entry> -<entry>Version:</entry> -<entry>Version:</entry> -<entry> -<para>Project version, used in generating the names of RPMs and -other deliverables that <application>shipper</application> -builds.</para> -</entry> -</row> -<row> -<entry><varname>homepage</varname></entry> -<entry>URL:</entry> -<entry>XBS-Home-Page:</entry> -<entry> -<para>Project home page URL. Used when generating project -announcements.</para> -</entry> -</row> -<row> -<entry><varname>arch</varname></entry> -<entry>BuildArch:</entry> -<entry>Architecture:</entry> -<entry> -<para>Build architecture. If this field is <quote>noarch</quote>, -noarch rather than binary RPMs will be built.</para> -</entry> -</row> -<row> -<entry><varname>keywords</varname></entry> -<entry>#Keywords:</entry> -<entry>XBS-Keywords:</entry> -<entry> -<para>Topic keywords. Used when generating LSM files.</para> -</entry> -</row> -<row> -<entry><varname>freshmeat_name</varname></entry> -<entry>#Freshmeat-Name:</entry> -<entry>XBS-Freshmeat-Name:</entry> -<entry> -<para>Freshmeat shortname, used in generating freshmeat.net -announcements. If this isn't present, it defaults to the project -name; you only need to set it if they differ.</para> -</entry> -</row> -<row> -<entry><varname>summary</varname></entry> -<entry>Summary</entry> -<entry>Description:</entry> -<entry> -<para>The one-line project summary field from your specfile.</para> -</entry> -</row> -<row> -<entry><varname>description</varname></entry> -<entry>%description</entry> -<entry>Description:</entry> -<entry> -<para>The Description field from your specfile.</para> -</entry> -</row> -<row> -<entry><varname>changelog</varname></entry> -<entry>ChangeLog or %changelog</entry> -<entry align='center'>-</entry> -<entry> -<para>If a <filename>ChangeLog</filename> file exists in the project -directory, its entire contents. Otherwise, if it exists, -the entire changelog section from the specfile.</para> -</entry> -</row> -<row> -<entry><varname>lastchange</varname></entry> -<entry>ChangeLog or %changelog</entry> -<entry align='center'>-</entry> -<entry> -<para> -If the source of your changlog was your specfile, this is the -most recent entry from your changelog without -its date/author/release header. If the source was Changelog, a -line of text directing the user to see the ChangeLog file. -This becomes the Changes field in your freshmeat.net announcement, -and freshmeat.net doesn't like the bulleted format of GNU ChangeLog -entries.</para> -</entry> -</row> -<row> -<entry><varname>resourcetable</varname></entry> <entry -align='center'>-</entry> <entry align='center'>-</entry> -<entry> -<para>The HTML table of links to downloadable resources. This -variable is only computed if the index page is built. Any setting -of it in the startup files is ignored.</para> -</entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para>All these variables are available for substitution at the time a -web page or email announcement is generated. In general, any variable -you set in your <filename>~/.shipper</filename> file will be available -at the time the web page or email announcement is generated. Use the -Python "%(variable)s" syntax, not shell-substitution syntax.</para> - -</refsect1> - -<refsect1><title>Finding and Building Local Deliverables</title> - -<para>The following files are considered stock deliverables and may be -shipped if they are present when <application>shipper</application> -starts up:</para> - -<informaltable> -<tgroup cols="2"> -<thead> -<row> -<entry>File</entry> -<entry>Explanation</entry> -</row> -</thead> -<tbody> -<row> -<entry>README</entry> -<entry> -<para>Project roadmap file.</para> -</entry> -</row> -<row> -<entry>tarball</entry> -<entry> -<para>The current source tarball, that is the file named ${package}-${version}.tar.gz.</para> -</entry> -</row> -<row> -<entry>zipfile</entry> -<entry> -<para>The current source zip archive, that is the file named ${package}-${version}.zip.</para> -</entry> -</row> -<row> -<entry>NEWS</entry> -<entry> -<para>Project news file.</para> -</entry> -</row> -<row> -<entry>ChangeLog</entry> -<entry> -<para>Project change log.</para> -</entry> -</row> -<row> -<entry>HISTORY</entry> -<entry> -<para>Project history file.</para> -</entry> -</row> -<row> -<entry>BUGS</entry> -<entry> -<para>Project bug list.</para> -</entry> -</row> -<row> -<entry>TODO</entry> -<entry> -<para>Current to-do list.</para> -</entry> -</row> -<row> -<entry>*.html</entry> -<entry> -<para>Any files with an .html extension will be shipped to all -website destinations.</para> -</entry> -</row> -</tbody> -</tgroup> -</informaltable> - -<para>Here are the generated deliverables that -<application>shipper</application> will build and ship, if they don't -exist when it starts up. Any of these that are created will be -deleted after a successful upload.</para> - -<informaltable> -<tgroup cols="2"> -<thead> -<row> -<entry>Type</entry> -<entry>Explanation</entry> -</row> -</thead> -<tbody> -<row> -<entry>index.html</entry> -<entry> -<para>An index web page, to be shipped to any website destination.</para> -</entry> -</row> -<row> -<entry>RPMs</entry> -<entry> -<para>Source and either binary or noarch RPMs.</para> -</entry> -</row> -<row> -<entry>LSM</entry> -<entry> -<para>If the ibiblio channel is enabled, -<application>shipper</application> will generate a Linux Software Map -file for it.</para> -</entry> -</row> -<row> -<entry>CHANGES</entry> -<entry> -<para>If there is no ChangeLog file but there was a %changelog in your -specfile, <application>shipper</application> will generate a CHANGES -from the changelog entries in the specfile and ship that.</para> -</entry> -</row> -<row> -<entry>ANNOUNCE.FRESHMEAT</entry> -<entry> -<para>If there is no ANNOUNCE.FRESHMEAT file, -<application>shipper</application> will generate one. It will be a -job card that can be fed to freshmeat.net's XML-RPC interface via -<citerefentry><refentrytitle>freshmeat-submit</refentrytitle><manvolnum>1</manvolnum></citerefentry>. -</para> -</entry> -</row> -<row> -<entry>ANNOUNCE.EMAIL</entry> -<entry> -<para>If there is no ANNOUNCE.EMAIL file, <application>shipper</application> -will generate one to be emailed to destinations that are mailto URLs.</para> -</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</refsect1> - -<refsect1><title>Shipping to Destinations</title> -<para>In operation, <application>shipper</application> walks through a -list of destinations, building the required deliverables for each one and -performing the required shipping actions to push them out to the -destination. Here are the channel types -<application>shipper</application> knows about:</para> - -<informaltable> -<tgroup cols="4"> -<colspec align='left'/> -<colspec align='left'/> -<colspec align='center'/> -<colspec align='left'/> -<thead> -<row> -<entry>Channel Type</entry> -<entry>Deliverables</entry> -<entry>Specified by</entry> -<entry>Explanation</entry> -</row> -</thead> -<tbody> -<row> -<entry>ibiblio</entry> -<entry>tarball, RPMs, LSM file</entry> -<entry>-</entry> -<entry> -<para>If the ibiblio channel is enabled (it is by default), -<application>shipper</application> will attempt to ship a source -tarball, RPMs, and an an LSM file to ibiblio.org via FTP. The LSM -file will be automatically generated.</para> -</entry> -</row> -<row> -<entry>redhat</entry> -<entry>RPMs</entry> -<entry>-</entry> -<entry> -<para>If the Red Hat channel is enabled (it is by default), -<application>shipper</application> will attempt to ship source -and binary RPMs to the Red Hat submission directory via FTP.</para> -</entry> -</row> -<row> -<entry>freshmeat</entry> -<entry>ANNOUNCE.FRESHMEAT</entry> -<entry>-</entry> -<entry> -<para>If the freshmeat channel is enabled (it is by default), -<application>shipper</application> will attempt to post a release -announcement on freshmeat.net using -<citerefentry><refentrytitle>freshmeat-submit</refentrytitle><manvolnum>1</manvolnum></citerefentry>. -The -announcement will include URLs for whichever of the following -deliverables are shipped, using the URL field from your specfile: tarball, -zipfile, RPMs, CHANGES. The user will be -prompted for a Freshmeat release-focus. This announcement is -generated into the local deliverable ANNOUNCE.FRESHMEAT.</para> -</entry> -</row> -<row> -<entry>Generic Web site</entry> -<entry>README, tarball, zipfile, RPMs, CHANGES, NEWS, HISTORY, *.html, -BUGS, TODO.</entry> -<entry>scp destination ([user@]host:dir)</entry> -<entry> -<para>This channel type represents a website. -<application>shipper</application> uses -<citerefentry><refentrytitle>scp</refentrytitle><manvolnum>1</manvolnum></citerefentry> -to put deliverables on websites. If the user part of the scp -destination is absent, it will be taken from the environment variable -<envar>USERNAME</envar>.</para> - -<para>No generic Web sites are shipped to by default. You must declare -them by putting scp destinations in the <varname>destinations</varname> -variable.</para> -</entry> -</row> -<row> -<entry>Generic FTP site</entry> -<entry>tarball, RPMs</entry> -<entry>FTP URL</entry> -<entry> -<para>Old-fashioned FTP site with no metadata. The FTP URL is parsed -to get the sitename and directory where deliverables should be dropped. The -FTP username to be used will be taken from the environment variable -<envar>USERNAME</envar>. The FTP password will be looked up in your -<filename>~/.netrc</filename> file.</para> - -<para>No generic FTP sites are shipped to by default. You must -declare them by putting FTP urls in the -<varname>destinations</varname> variable.</para> -</entry> -</row> -<row> -<entry>Email address</entry> -<entry>ANNOUNCE.EMAIL</entry> -<entry>mailto URL</entry> -<entry> -<para>The contents of the generated ANNOUNCE.EMAIL file is emailed to -each email address specified as a channel.</para> - -<para>No email channels are set up by default. You must -declare them by putting mailto: urls in the -<varname>destinations</varname> variable.</para> -</entry> -</row> -<row> -<entry>rsync unit</entry> -<entry>SRPM</entry> -<entry>rsync address ([user@]host::unit)</entry> -<entry> -<para>An SRPM is shipped to each destination that is rcognized as -an rsync address (by the double colon).</para> - -<para>No rsync channels are set up by default. You must -declare them by putting rsync addresses in the -<varname>destinations</varname> variable.</para> -</entry> -</row> -</tbody> -</tgroup> -</informaltable> -</refsect1> - -<refsect1><title>Command-line Options</title> - -<para>The -n option of <application>shipper</application> suppresses -uploads, just building all deliverables locally. The -N option -suppresses both uploads and builds, generating a configuration dumop -instead. The -f option forces rebuilding of local deliverables even -if they already exist. The -v option makes -<application>shipper</application> chatty about what it's doing. The --h option prints a usage message and exits.</para> - -</refsect1> - -<refsect1><title>Hints and Tips</title> -<para>The following variable definition in your makefile will ensure -that the makefile version is derived from (and thus always consistent -with) the specfile version.</para> - -<programlisting> -VERS=$(shell sed <*.spec -n -e '/Version: \(.*\)/s//\1/p') -</programlisting> - -<para>A makefile production like the following will allow -you to type <command>make release</command> and be sure that all -the deliverables <application>shipper</application> knows about -will be rebuilt before being shipped.</para> - -<programlisting> -release: <emphasis>package</emphasis>-$(VERS).tar.gz <emphasis>package</emphasis>.html - shipper -f -</programlisting> - -<para>You will want to change <emphasis>package</emphasis> to your -project name. Note that you should not use this recipe if your -project has its own (non-generated) index page, as the -f option will -overwrite <filename>index.html</filename>.</para> - -<para>To make -<citerefentry> -<refentrytitle>rpm</refentrytitle><manvolnum>1</manvolnum> -</citerefentry> -build noarch rather than binary RPMs, insert the following header in -your specfile:</para> - -<programlisting> -BuildArch: noarch -</programlisting> -</refsect1> - -<refsect1><title>Author</title> -<para>Eric S. Raymond <email>esr@thyrsus.com</email>. The buildrpms -script was originally by Sean Reifschneider.</para> - -<para>There is a project web page at -<ulink -url="http://www.catb.org/~esr/shipper/">http://www.catb.org/~esr/shipper/</ulink>.</para> -</refsect1> - -<refsect1><title>Bugs</title> -<para>The rsync channel type is untested. Shipping Debian packages -should be supported.</para> -</refsect1> - -<refsect1><title>See Also</title> - -<para> -<citerefentry> -<refentrytitle>freshmeat-submit</refentrytitle> -<manvolnum>1</manvolnum> -</citerefentry>, -<citerefentry> -<refentrytitle>lftp</refentrytitle> -<manvolnum>1</manvolnum> -</citerefentry>, -<citerefentry> -<refentrytitle>rpm2lsm</refentrytitle> -<manvolnum>1</manvolnum> -</citerefentry>, -<citerefentry> -<refentrytitle>scp</refentrytitle> -<manvolnum>1</manvolnum> -</citerefentry>, -<citerefentry> -<refentrytitle>ssh</refentrytitle> -<manvolnum>1</manvolnum> -</citerefentry>.</para> -</refsect1> -</refentry> - -<!-- -Local Variables: -compile-command: "make shipper.html" -End: ---> |