Information for Maintainers of GNU Software Notes

Source: http://www.gnu.org/prep/maintain/maintain.html

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

Here is how to register your information so you can perform uploads for your GNU package:

  1. 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).
  2. 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-keys keyid, where keyid is the eight hex digits reported by gpg --list-public-keys on the pub line before the date. For full information about GPG, see http://www.gnu.org/software/gpg.

  3. Compose a message with the following items in some msgfile. Then GPG-sign it by running gpg --clearsign msgfile, and finally email the resulting ‘msgfile.asc’ to ftp-upload@gnu.org.
    1. Name of package(s) that you are the maintainer for, your preferred email address, and your Savannah username.
    2. An ASCII armored copy of your GPG key, as an attachment. (‘gpg –export -ayour_key_id>mykey.asc’ should give you this.)
    3. 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).
    4. ASCII armored copies of GPG keys for any individuals listed in (3).

11.5.2 Automated Upload Procedure

Once you have registered your information as described in the previous section, you will be able to do ftp uploads for yourself using the following procedure.

For each upload destined for ftp.gnu.org or alpha.gnu.org, three files (a triplet) need to be uploaded via ftp to the host ftp-upload.gnu.org.

  1. The file to be distributed; for example, ‘foo.tar.gz’.
  2. Detached GPG binary signature file for (1); for example, ‘foo.tar.gz.sig’. Make this with ‘gpg -b foo.tar.gz’.
  3. 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 ftp.

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 <http://www.gnu.org/software/package/>. 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.

12.3.1 Invoking gendocs.sh

The script 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:

http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh
http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template

There is also a minimalistic template, available from:

http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min

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 bug-package@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 bug-texinfo@gnu.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 bug-texinfo@gnu.org -o texinfo texinfo "GNU Texinfo manual"
gendocs.sh --email bug-texinfo@gnu.org -o info info "GNU Info manual"
gendocs.sh --email bug-texinfo@gnu.org -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 MAKEINFO, TEXI2DVI, TEXI2HTML and 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.

16 Donations

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 bug-directory@gnu.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: proofreaders@gnu.org.

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!

发表评论

电子邮件地址不会被公开。 必填项已用*标注

*