trusty (1) freecode-submit.1.gz
NAME
freecode-submit - submit release announcements and project metadata updates to freecode.com
SYNOPSIS
freecode-submit [-q] [-V] [-n] [-N] [-d] [--showversion] [data-options] [data-options...]
DESCRIPTION
freecode-submit is a command-line tool for submitting release announcements to freecode.com. It is
intended for batch-mode operation in project release scripts, and designed so that its input format can
easily be generated by scripts.
freecode-submit accepts release information from a job card (an email-message-like data block on standard
input) or from command-line flags. Values set with command-line flags override those collected from the
job card. The accumulated data is entered into the freecode database via its API.
A few flags control the operation of freecode-submit itself.
-q, --query
Query the specified project. Delivers to standard output a job card describing the project metadata
that can be edited and fed back to this tool. The data with release rather than project scope is for
the most recent release.
-d, --delete
Delete the specified release rather than submitting it. With this option, all data other than Project
and Release are ignored. Note: only works if the release has been submitted but not yet passed by a
moderator; if the release is already posted, invoking this mode will throw an error.
-n, --no-stdin
Process command-line options only; don't read data from standard input.
-N, --dryrun
Generate JSON, but don't ship any modification requests to Freecode. Useful for debugging in
combination with -V. Note, this mode may generate requests which read data from Freecode in order to
get permalink data.
-V, --verbose
Enable verbose debugging of the transaction. This option is mainly for developers.
--showversion
Show the version of this program and exit.
Release information is accepted from sources in the following order:
1. An RFC-2822-format job card, strongly resembling an ordinary email message, on standard input. The
message header fields each specify a particular item of release information; the body (if present)
becomes the change announcement text. Within URL fields, the string ${version} will be replaced with
the contents of the Version field.
2. Command-line switches.
Here is a table of metadata fields and their corresponding command-line switches:
┌──────────────────┬─────────┬──────────────┬────────────────────┬────────────────────────┐
│Message field │ Scope │ Short switch │ Long switch │ Explanation │
├──────────────────┼─────────┼──────────────┼────────────────────┼────────────────────────┤
│Project: │ Project │ -P │ --project │ │
│ │ │ │ │ Name of the │
│ │ │ │ │ project │
│ │ │ │ │ (freecode │
│ │ │ │ │ shortname) │
│ │ │ │ │ to operate │
│ │ │ │ │ on. You │
│ │ │ │ │ cannot │
│ │ │ │ │ change the │
│ │ │ │ │ project-name │
│ │ │ │ │ attribute │
│ │ │ │ │ with this │
│ │ │ │ │ program; to │
│ │ │ │ │ do that, you │
│ │ │ │ │ need to use │
│ │ │ │ │ the Freecode │
│ │ │ │ │ web │
│ │ │ │ │ interface. │
├──────────────────┼─────────┼──────────────┼────────────────────┼────────────────────────┤
│Summary: │ Project │ -S │ --summary │ │
│ │ │ │ │ One-line │
│ │ │ │ │ summary of │
│ │ │ │ │ the project. │
├──────────────────┼─────────┼──────────────┼────────────────────┼────────────────────────┤
│Description: │ Project │ -D │ --description │ │
│ │ │ │ │ Multiline │
│ │ │ │ │ description │
│ │ │ │ │ of the │
│ │ │ │ │ project. │
│ │ │ │ │ (Use │
│ │ │ │ │ RFC-822-style │
│ │ │ │ │ continuation │
│ │ │ │ │ lines) │
├──────────────────┼─────────┼──────────────┼────────────────────┼────────────────────────┤
│License-List: │ Project │ -L │ --license-list │ │
│ │ │ │ │ Specify the │
│ │ │ │ │ licenses │
│ │ │ │ │ under which │
│ │ │ │ │ the project │
│ │ │ │ │ is issued. │
│ │ │ │ │ This may be a │
│ │ │ │ │ comma-separated │
│ │ │ │ │ list. │
├──────────────────┼─────────┼──────────────┼────────────────────┼────────────────────────┤
│Project-Tag-List: │ Release │ -T │ --project-tag-list │ │
│ │ │ │ │ Tags to attach │
│ │ │ │ │ to this │
│ │ │ │ │ project. May be │
│ │ │ │ │ a │
│ │ │ │ │ comma-separated │
│ │ │ │ │ list. │
├──────────────────┼─────────┼──────────────┼────────────────────┼────────────────────────┤
│Version: │ Release │ -v │ --version │ │
│ │ │ │ │ Version string │
│ │ │ │ │ to be │
│ │ │ │ │ associated with │
│ │ │ │ │ the release. │
├──────────────────┼─────────┼──────────────┼────────────────────┼────────────────────────┤
│Changes: │ Release │ -c │ --changes │ │
│ │ │ │ │ The Changes │
│ │ │ │ │ field. If no │
│ │ │ │ │ Changes field │
│ │ │ │ │ or option is │
│ │ │ │ │ already │
│ │ │ │ │ present, the │
│ │ │ │ │ changes text is │
│ │ │ │ │ taken from the │
│ │ │ │ │ body of the │
│ │ │ │ │ RFC-822 message │
│ │ │ │ │ on standard │
│ │ │ │ │ input. │
├──────────────────┼─────────┼──────────────┼────────────────────┼────────────────────────┤
│Release-Tag-List: │ Release │ -t │ --tag-list │ │
│ │ │ │ │ Tags to attach │
│ │ │ │ │ to this │
│ │ │ │ │ release. May be │
│ │ │ │ │ a │
│ │ │ │ │ comma-separated │
│ │ │ │ │ list. │
├──────────────────┼─────────┼──────────────┼────────────────────┼────────────────────────┤
│Hide: │ Release │ -x │ --hide │ │
│ │ │ │ │ If this field │
│ │ │ │ │ is present and │
│ │ │ │ │ has the value │
│ │ │ │ │ “Y”, this │
│ │ │ │ │ release will │
│ │ │ │ │ not be visible │
│ │ │ │ │ on the project │
│ │ │ │ │ page. │
└──────────────────┴─────────┴──────────────┴────────────────────┴────────────────────────┘
Additionally, you can specify tagged URL fields for the Freecode project record with header lines ending
in "-URL:". The tag will be the header with the "-URL:" suffix stripped off. Some examples of how to set
frequently-used URL types:
┌──────────────┬───────────┬──────────────────────────────┐
│Message field │ Tag │ Usage │
├──────────────┼───────────┼──────────────────────────────┤
│Website-URL: │ Website │ Project website home page. │
│ │ │ If you specify this, it will │
│ │ │ be used to │
│ │ │ activate the "More │
│ │ │ Information" link and Home │
│ │ │ icon on the project page. │
├──────────────┼───────────┼──────────────────────────────┤
│Download-URL: │ Download │ Preferred download URL. If │
│ │ │ you specify this, it will be │
│ │ │ used to │
│ │ │ activate the "Download" │
│ │ │ link and floppy-disk icon on │
│ │ │ the project page. │
├──────────────┼───────────┼──────────────────────────────┤
│Tar/GZ-URL: │ Tar/GZ │ tar archive compressed with │
│ │ │ gzip │
├──────────────┼───────────┼──────────────────────────────┤
│Tar/BZ-URL: │ Tar/BZ │ tar archive compressed with │
│ │ │ bzip │
├──────────────┼───────────┼──────────────────────────────┤
│Changelog-URL │ Changelog │ project change log │
└──────────────┴───────────┴──────────────────────────────┘
Note that the list of URLs you ship does not merely add to the existing list but overwrites it - that is
how you delete old URLs which are no longer valid.
The Summary, Description, License-List, Project-Tag-List and all URL fields, when specified, actually
change the record for the project. Only the Tag-List, Changes, Version, and Hide fields are actually
stored for each version.
The following elements of Freecode project metadata cannot yet be modified using this tool: name,
translation list, programming language list, operating system list, approved screenshots, and dependency
records.
Support for updating all these elements except name is planned in future releases.
USAGE
Here is an example of a release-information record that could be fed to freecode-submit on standard
input:
Project: doclifter
Version: 1.1
Hide: N
Website-URL: http://www.catb.org/~esr/doclifter/
Tar/GZ-URL: http://www.catb.org/~esr/doclifter/doclifter-${version}.tar.gz
Fixed a bug in conditional evaluation that twadmin(8) tickled. Better
detection of pure inclusions. Better blank-section elimination.
Kleene star recognized as ... synonym in command synopses. Correct
some bugs in semantic-hint collection. Recognize Qt manual pages and
use their conventions. Better lifting of mandoc-generated
pages. Translate groff-style \[...] escapes, flag unknown ones. Can
now parse K&R style function prototypes as well as ANSI ones. This
version lifts 96% of 9829 manual pages in a full Red Hat 9
installation with Fedora updates to *validated* XML-DocBook.
WARNING
Since this program was first written, Freecode has changed its data API significantly (and its name, too;
it used to be 'Freshmeat'). While we have attempted to maintain backward compatibility, the data model
has changed in significant ways.
There is no longer a Branch attribute.
The old Release-Focus field is gone.
The old License field is now License-List and can take a comma-separated list of licenses.
All the old URL fields are gone. They're replaced by the general mechanism for pairing URLs with labels.
Earlier versions parsed RPM specfiles. This was poor separation of function and has been removed. That
responsibility belongs to the human or program generating the job card.
FILES
~/.netrc freecode-submit expects to find your Freecode authorization tag here. The correct form for an entry looks like this: machine freecode account <your_api_auth_code> password none For security, make sure your ~/.netrc file is not world-readable; we recommend doing chmod 600 ~/.netrc.
BUGS
The URLs returned in a project metadata query are Freecode redirectors, not the actual URLS supplied by
previous project updates. This is due to a limitation in the Freecode API which may be fixed in future
versions of that API.
RETURN VALUES
0 on success, 1 on failure. In case of failure, any error message passed back by the Freecode API is
issued to standard error.
AUTHORS
Eric S. Raymond <esr@thyrsus.com>.