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.
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.
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.
Process command-line options only; don't read data from standard input.
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.
Enable verbose debugging of the transaction. This option is mainly for developers.
Show the version of this program and exit.
Release information is accepted from sources in the following order:
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.
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.
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.
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.
~/.netrcfreecode-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.
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.