Information for Maintainers of GNU Software Notes
3 Getting a GNU Account
The directory ‘/gd/gnuorg’ mentioned throughout this document is available on the general GNU server, currently
fencepost.gnu.org. If you are the maintainer of a GNU package, you should have an account there. If you don’t have one already, http://www.gnu.org/software/README.accounts.html. You can also ask for accounts for people who significantly help you in working on the package.
11.5.1 Automated Upload Registration
- Create an account for yourself at http://savannah.gnu.org, if you don’t already have one. By the way, this is also needed to maintain the web pages at http://www.gnu.org for your project (see Web Pages).
- In the ‘My Account Conf’ page on
savannah, upload the GPG key you will use to sign your packages. If you haven’t created one before, you can do so with the command
gpg --gen-key(you can accept all the default answers to its questions).
Optional but recommended: Send your key to a GPG public key server:
gpg --keyserver keys.gnupg.net --send-keyskeyid, where keyid is the eight hex digits reported by
gpg --list-public-keyson the
publine before the date. For full information about GPG, see http://www.gnu.org/software/gpg.
- Compose a message with the following items in some msgfile. Then GPG-sign it by running
gpg --clearsignmsgfile, and finally email the resulting ‘msgfile.asc’ to email@example.com.
- Name of package(s) that you are the maintainer for, your preferred email address, and your Savannah username.
- An ASCII armored copy of your GPG key, as an attachment. (‘gpg –export -ayour_key_id>mykey.asc’ should give you this.)
- A list of names and preferred email addresses of other individuals you authorize to make releases for which packages, if any (in the case that you don’t make all releases yourself).
- ASCII armored copies of GPG keys for any individuals listed in (3).
11.5.2 Automated Upload Procedure
For each upload destined for
alpha.gnu.org, three files (a triplet) need to be uploaded via ftp to the host
- The file to be distributed; for example, ‘foo.tar.gz’.
- Detached GPG binary signature file for (1); for example, ‘foo.tar.gz.sig’. Make this with ‘gpg -b foo.tar.gz’.
- A clearsigned directive file; for example, ‘foo.tar.gz.directive.asc’. Make this by preparing the plain text file ‘foo.tar.gz.directive’ and then run ‘gpg –clearsign foo.tar.gz.directive’. See FTP Upload Directive File – v1.1, for the contents of the directive file.
Your designated upload email addresses (see Automated Upload Registration) are sent a message if there are any problems processing an upload for your package. You also receive a message when your upload has been successfully processed.
One automated way to create and transfer the necessary files is to use the
gnupload script, which is available from the ‘build-aux/’ directory of the
gnulib project at http://savannah.gnu.org/projects/gnulib.
gnupload can also remove uploaded files. Run
gnupload --help for a description and examples.
gnupload uses the
ncftpput program to do the actual transfers; if you don’t happen to have the
ncftp package installed, the
ncftpput-ftp script in the ‘build-aux/’ directory of
gnulib serves as a replacement which uses plain command line
12 Web Pages
Please write web pages about your package, and install them on
www.gnu.org. They should follow our usual standards for web pages (see http://www.gnu.org/server/fsf-html-style-sheet.html). The overall goals are to support a wide variety of browsers, to focus on information rather than flashy eye candy, and to keep the site simple and uniform.
We encourage you to use the standard
www.gnu.org template as the basis for your pages: http://www.gnu.org/server/standards/boilerplate-source.html.
12.1 Hosting for Web Pages
The best way to maintain the web pages for your project is to register the project on
savannah.gnu.org. Then you can edit the pages using CVS, using the separate “web repository” available on Savannah, which corresponds to <
/>. You can keep your source files there too (using any of a variety of version control systems), but you can use
savannah.gnu.org only for your gnu.org web pages if you wish; simply register a “web-only” project.
gendocs.sh eases the task of generating the Texinfo documentation output for your web pages section above. It has a companion template file, used as the basis for the HTML index pages. Both are available from the Texinfo CVS sources:
There is also a minimalistic template, available from:
Invoke the script like this, in the directory containing the Texinfo source:
gendocs.sh --email yourbuglist yourmanual "GNU yourmanual manual"
where yourmanual is the short name for your package and yourbuglist is the email address for bug reports (which should be
@gnu.org). The script processes the file ‘yourmanual.texinfo’ (or ‘.texi’ or ‘.txi’). For example:
cd .../texinfo/doc # download gendocs.sh and gendocs_template gendocs.sh --email firstname.lastname@example.org texinfo "GNU Texinfo manual"
gendocs.sh creates a subdirectory ‘manual/’ containing the manual generated in all the standard output formats: Info, HTML, DVI, and so on, as well as the Texinfo source. You then need to move all those files, retaining the subdirectories, into the web pages for your package.
You can specify the option ‘-ooutdir’ to override the name ‘manual’. Any previous contents of outdir will be deleted.
The second argument, with the description, is included as part of the HTML
<title> of the overall ‘manual/index.html’ file. It should include the name of the package being documented, as shown. ‘manual/index.html’ is created by substitution from the file ‘gendocs_template’. (Feel free to modify the generic template for your own purposes.)
If you have several manuals, you’ll need to run this script several times with different arguments, specifying a different output directory with ‘-o’ each time, and moving all the output to your web page. Then write (by hand) an overall index.html with links to them all. For example:
cd .../texinfo/doc gendocs.sh --email email@example.com -o texinfo texinfo "GNU Texinfo manual" gendocs.sh --email firstname.lastname@example.org -o info info "GNU Info manual" gendocs.sh --email email@example.com -o info-stnd info-stnd "GNU info-stnd manual"
By default, the script uses
makeinfo for generating HTML output. If you prefer to use
texi2html, use the ‘–texi2html’ command line option, e.g.:
gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"
The template files will automatically produce entries for additional HTML output generated by
texi2html (i.e., split by sections and chapters).
You can set the environment variables
DVIPS to control the programs that get executed, and
GENDOCS_TEMPLATE_DIR to control where the ‘gendocs_template’ file is found.
As usual, run ‘gendocs.sh –help’ for a description of all the options, environment variables, and more information.
As a maintainer, you might want to accept donations for your work, especially if you pay for any of your own hosting/development infrastructure. Following is some text you can adapt to your own situation, and use on your package’s web site, ‘README’, or in wherever way you find it useful:
We appreciate contributions of any size -- donations enable us to spend more time working on the project, and help cover our infrastructure expenses. If you'd like to make a small donation, please visit url1 and do it through payment-service. Since our project isn't a tax-exempt organization, we can't offer you a tax deduction, but for all donations over amount1, we'd be happy to recognize your contribution on url2. We are also happy to consider making particular improvements or changes, or giving specific technical assistance, in return for a substantial donation over amount2. If you would like to discuss this possibility, write to us at address. Another possibility is to pay a software maintenance fee. Again, write to us about this at address to discuss how much you want to pay and how much maintenance we can offer in return. If you pay more than amount1, we can give you a document for your records. Thanks for your support!
We don’t recommend any specific payment service. However, GNU developers should not use a service that requires them to sign a proprietary software license, such as Google’s payment service.
Of course, it is also good to encourage people to join or contribute to the FSF (http://www.fsf.org), either instead of or as well as package-specific donations.
17 Free Software Directory
The Free Software Directory aims to be a complete list of free software packages, within certain criteria. Every GNU package should be listed there, so please see http://www.gnu.org/help/directory.html#adding-entries for information on how to write an entry for your package. Contact firstname.lastname@example.org with any questions or suggestions for the Free Software Directory.
18 Using the Proofreaders List
If you want help finding errors in documentation, or help improving the quality of writing, or if you are not a native speaker of English and want help producing good English documentation, you can use the GNU proofreaders mailing list: email@example.com.
But be careful when you use the list, because there are over 200 people on it. If you simply ask everyone on the list to read your work, there will probably be tremendous duplication of effort by the proofreaders, and you will probably get the same errors reported 100 times. This must be avoided.
Also, the people on the list do not want to get a large amount of mail from it. So do not ever ask people on the list to send mail to the list!