From 490e0ce2f0d43ea05e582aaa06517348cb4cab4e Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 7 Jan 2013 08:58:19 -0800 Subject: [PATCH] autoupdate --- doc/maintain.texi | 443 +++++++++++++++++++++++++++++----------------- 1 file changed, 278 insertions(+), 165 deletions(-) diff --git a/doc/maintain.texi b/doc/maintain.texi index dcea193dab..5bde4c82c9 100644 --- a/doc/maintain.texi +++ b/doc/maintain.texi @@ -5,7 +5,7 @@ @c For double-sided printing, uncomment: @c @setchapternewpage odd @c This date is automagically updated when you save this file: -@set lastupdate January 1, 2013 +@set lastupdate January 6, 2013 @c %**end of header @dircategory GNU organization @@ -1496,7 +1496,11 @@ before they are made publicly available. @menu * Automated Upload Registration:: * Automated Upload Procedure:: -* FTP Upload Directive File - v1.2:: +* FTP Upload Release File Triplet:: +* FTP Upload Directive File:: +* FTP Upload Directory Trees:: +* FTP Upload File Replacement:: +* FTP Upload Standalone Directives:: * FTP Upload Directive File - v1.1:: * FTP Upload Directive File - v1.0:: @end menu @@ -1569,254 +1573,358 @@ when an upload is made, either successfully or unsuccessfully. @cindex uploads 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. +section, you can and should do ftp uploads for your package. There +are two basic kinds of uploads (details in the following sections): -For each upload destined for @code{ftp.gnu.org} or -@code{alpha.gnu.org}, three files (a @dfn{triplet}) need to be -uploaded via ftp to the host @code{ftp-upload.gnu.org}. +@enumerate +@item +Three related files (a ``triplet'') to upload a file destined for +@code{ftp.gnu.org} or @code{alpha.gnu.org}: @pxref{FTP Upload Release +File Triplet}. + +@item +A single (signed) standalone ``directive file'' to perform operations +on the server: @pxref{FTP Upload Standalone Directives}. +@end enumerate + +In either case, you upload the file(s) via anonymous ftp to the host +@code{ftp-upload.gnu.org}. If the upload is destined for +@code{ftp.gnu.org}, place the file(s) in the directory +@file{/incoming/ftp}. If the upload is destined for +@code{alpha.gnu.org}, place the file(s) in the directory +@file{/incoming/alpha}. + +Uploads are processed every five minutes. Uploads that are in +progress while the upload processing script is running are handled +properly, so do not worry about the timing of your upload. Spurious +and stale uploaded files are deleted automatically after 24 hours. + +Your designated upload email addresses (@pxref{Automated Upload +Registration}) are sent a message if there are problems processing an +upload for your package. You also receive a message when an upload +has been successfully processed. + +One programmatic way to create and transfer the necessary files is to +use the @code{gnupload} script, which is available from the +@file{build-aux/} directory of the @code{gnulib} project at +@url{http://savannah.gnu.org/projects/gnulib}. Run +@code{gnupload@tie{}--help} for a description and examples. + +@code{gnupload} invokes the program @code{ncftpput} to do the actual +transfers; if you don't happen to have the @code{ncftp} package +installed, the @code{ncftpput-ftp} script in the @file{build-aux/} +directory of @code{gnulib} can serve as a replacement. It uses the +plain command line @code{ftp} program. + +If you have difficulties with an upload, email +@email{ftp-upload@@gnu.org}. You can check the archive of uploads +processed at +@url{https://lists.gnu.org/archive/html/ftp-upload-report}. + + +@node FTP Upload Release File Triplet +@subsection FTP Upload Release File Triplet + +@cindex FTP uploads, of release files + +Ordinarily, the goal is to upload a new release of your package, let's +say, the source archive @file{foo-1.0.tar.gz}. To do this, you +simultaneously upload three files: @enumerate @item -The file to be distributed; for example, @file{foo.tar.gz}. +The file to be distributed; in our example, @file{foo-1.0.tar.gz}. @item Detached GPG binary signature file for (1); for example, -@file{foo.tar.gz.sig}. Make this with @samp{gpg -b foo.tar.gz}. +@file{foo-1.0.tar.gz.sig}. Make this with @samp{gpg -b foo-1.0.tar.gz}. @item A clearsigned @dfn{directive file}; for example, -@file{foo.tar.gz.directive.asc}. Make this by preparing the plain -text file @file{foo.tar.gz.directive} and then run @samp{gpg ---clearsign foo.tar.gz.directive}. @xref{FTP Upload Directive File - -v1.1}, for the contents of the directive file. +@file{foo-1.0.tar.gz.directive.asc}, created with @samp{gpg +--clearsign foo-1.0.tar.gz.directive}. Its contents are described in +the next section. @end enumerate -The names of the files are important. The signature file must have the -same name as the file to be distributed, with an additional -@file{.sig} extension. The directive file must have the same name as +The names of the files are important. The signature file must have +the same name as the file to be distributed, with an additional +@file{.sig} extension. The directive file must have the same name as the file to be distributed, with an additional @file{.directive.asc} -extension. If you do not follow this naming convention, the upload +extension. If you do not follow this naming convention, the upload @emph{will not be processed}. -Since v1.1 of the upload directives, it is also possible to upload a -clearsigned directive file on its own (no accompanying @file{.sig} or -any other file) to perform certain operations on the server. -@xref{FTP Upload Directive File - v1.1}, for more information. -Upload the file(s) via anonymous ftp to @code{ftp-upload.gnu.org}. If -the upload is destined for @code{ftp.gnu.org}, place the file(s) in -the @file{/incoming/ftp} directory. If the upload is destined for -@code{alpha.gnu.org}, place the file(s) in the @file{/incoming/alpha} -directory. +@node FTP Upload Directive File +@subsection FTP Upload Directive File -Uploads are processed every five minutes. Uploads that are in -progress while the upload processing script is running are handled -properly, so do not worry about the timing of your upload. Uploaded -files that belong to an incomplete triplet are deleted automatically -after 24 hours. +@cindex directive file, for FTP uploads -Your designated upload email addresses (@pxref{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. +To repeat, a (signed) @dfn{directive file} must be part of every +upload. The unsigned original is just a plain text file you can +create with any text editor. Its name must be, e.g., +@file{foo-1.0.tar.gz.directive} for accompanying an upload of +@file{foo-1.0.tar.gz}. -One automated way to create and transfer the necessary files is to use -the @code{gnupload} script, which is available from the -@file{build-aux/} directory of the @code{gnulib} project at -@url{http://savannah.gnu.org/projects/gnulib}. @code{gnupload} can -also remove uploaded files. Run @code{gnupload --help} for a -description and examples. +After creating the file, run @samp{gpg --clearsign +foo-1.0.tar.gz.directive}, which will create +@file{foo-1.0.tar.gz.directive.asc}; this is the file to be uploaded. -@code{gnupload} uses the @code{ncftpput} program to do the actual -transfers; if you don't happen to have the @code{ncftp} package -installed, the @code{ncftpput-ftp} script in the @file{build-aux/} -directory of @code{gnulib} serves as a replacement which uses plain -command line @code{ftp}. +When part of a triplet for uploading a release file, the directive +file must always contain the directives @code{version}, +@code{filename} and @code{directory}. In addition, a @code{comment} +directive is optional. These directives can be given in any order. -If you have difficulties with an upload, email -@email{ftp-upload@@gnu.org}. You can check the archive of uploads -processed at -@url{https://lists.gnu.org/archive/html/ftp-upload-report}. +Continuing our example of uploading @file{foo-1.0.tar.gz} for a +package named @code{foo} to @code{ftp.gnu.org}, the values would be as +follows: +@table @code +@item version +must be the value @samp{1.2} (the current version, as of May@tie{}2012):@* +@t{version: 1.2} -@node FTP Upload Directive File - v1.2 -@subsection FTP Upload Directive File - v1.2 +@item filename +must be the name of the file to be distributed:@* +@t{filename: foo-1.0.tar.gz} -All the directives and documentation for v1.1 of the protocol still -apply. @xref{FTP Upload Directive File - v1.1}, for more information. +@item directory +specifies the final destination directory where the uploaded file and +its @file{.sig} companion are to be placed. Here we will put our file +in the top level directory of the package, as is the most common +practice:@* +@t{directory: foo} -@subheading New directive @code{replace} +@item comment +is optional, and ignored if present:@* +@t{comment: let's hope this works!} +@end table -@cindex replacing uploaded files -@cindex uploads, replacing -As part of an uploaded triplet, a @file{foo.tar.gz.directive.asc} file -might contain these lines (before being GPG-clearsigned): +Putting the above together, the complete contents of the directive +file @file{foo-1.0.tar.gz.directive} for our example would be: @example version: 1.2 -directory: bar/v1 -filename: foo.tar.gz -comment: hello world! +directory: foo +filename: foo-1.0.tar.gz +comment: let's hope this works! @end example -If @file{foo.tar.gz} exists prior to upload, this directive file will -result in an error. Prior to May 2012, the behavior (of v1.1) was -different: any existing files were automatically archived and replaced -with the new upload. Since May 2012, no files are replaced unless the -(new) @code{replace} directive is set to @code{true} in the directive -file. That directive requires version 1.2 of the protocol. For -example: +Then you @samp{gpg --clearsign} the file as given above, and upload +(using anonymous ftp) the three files: + +@table @file +@item foo-1.0.tar.gz +@item foo-1.0.tar.gz.sig +@item foo-1.0.tar.gz.directive +@end table + +@noindent to the host @file{ftp-upload.gnu.org}, directory +@file{/incoming/ftp} (for official releases), or the directory +@file{/incoming/alpha} (for test releases). + +After the system authenticates the signatures, the files +@file{foo-1.0.tar.gz} and @file{foo-1.0.tar.gz.sig} are placed in +the directory @file{gnu/foo/} on @code{ftp.gnu.org}. That is, we'll +have made our release available at +@indicateurl{http://ftp.gnu.org/gnu/foo/foo-1.0.tar.gz} (and then from +our many mirrors via +@indicateurl{http://ftpmirror.gnu.org/foo/foo-1.0.tar.gz}). Whew. + +A common reason for the upload not succeeding is your GPG signature +not being registered with the upload system. There is nothing that +makes this happen automatically. You must email the system +administrators as described above (@pxref{Automated Upload +Registration}). + + +@node FTP Upload Directory Trees +@subsection FTP Upload Directory Trees + +@cindex directory trees, in ftp uploads +@cindex hierarchy, under ftp upload directory +@cindex uploads, directory trees in + +You can make any directory hierarchy you like under your package +directory. The system automatically creates any intermediate +directories you specify in the @code{directory} directive. + +Slightly modifying the example above, the following directive file: @example version: 1.2 -directory: bar/v1 -filename: foo.tar.gz +directory: foo/foo-1.0 +filename: foo-1.0.tar.gz +comment: creates per-version subdirectory as needed +@end example + +@noindent +would put the tar file in the @file{foo-1.0/} subdirectory of the +package @code{foo}, thus ending up at +@indicateurl{ftp.gnu.org:gnu/foo/foo-1.0/foo-1.0.tar.gz}. + +However, to keep things simpler for users, we recommend not using +subdirectories, unless perhaps each release of your package consists +of many separate files. + + +@node FTP Upload File Replacement +@subsection FTP Upload File Replacement + +@cindex replacing uploaded files +@cindex uploads, replacing + +You can replace existing files that have already been uploaded by +including a directive line @code{replace:@tie{}true}. For example, +you might like to provide a README file in the release directory and +update it from time to time. The full directive file for that would +look like this: + +@example replace: true -comment: hello world! +version: 1.2 +directory: foo +filename: README +comment: replaces an existing README @end example +It is ok if the file to be replaced doesn't already exist; then the +new file is simply added, i.e., the @file{replace} directive has no +effect. -@node FTP Upload Directive File - v1.1 -@subsection FTP Upload Directive File - v1.1 +When an existing file is replaced, the original is archived to a +private location. There is no automated or public access to such +archived files; if you want to retrieve or view them, please email +@email{sysadmin@@fsf.org}. -The directive file name must end in @file{directive.asc}. +We very strongly discourage replacing an actual software release file, +such as @file{foo-1.0.tar.gz}. Releases should be unique, and +forever. If you need to make fixes, make another release. If you +have an exigent reason for a particular release file to no longer be +available, it can be explicitly archived, as described in the next +section. -When part of a triplet, the directive file must always contain the -directives @code{version}, @code{directory} and @code{filename}, as -described. In addition, a @code{comment} directive is allowed. +If you want to make the current release available under a generic +name, such as @code{foo-latest.tar.gz}, that is better done with +symlinks, also as described in the next section. -The @code{version} directive must always have the value @samp{1.1}. -The @code{directory} directive specifies the final destination -directory where the uploaded file and its @file{.sig} companion are to -be placed. +@node FTP Upload Standalone Directives +@subsection FTP Upload Standalone Directives -The @code{filename} directive must contain the name of the file to be -distributed (item@tie{}(1) above). +@cindex standalone directives, for ftp uploads +@cindex directives for ftp uploads, standalone -For example, as part of an uploaded triplet, a -@file{foo.tar.gz.directive.asc} file might contain these lines (before -being gpg clearsigned): +The previous sections describe how to upload a file to be publicly +released. It's also possible to upload a directive file by itself to +perform a few operations on the upload directory. The supported +directives are: -@example -version: 1.1 -directory: bar/v1 -filename: foo.tar.gz -comment: hello world! -@end example +@table @code +@item symlink +creates a symlink. -This directory line indicates that @file{foo.tar.gz} and -@file{foo.tar.gz.sig} are part of package @code{bar}. If you uploaded -this triplet to @file{/incoming/ftp} and the system positively -authenticates the signatures, the files @file{foo.tar.gz} and -@file{foo.tar.gz.sig} will be placed in the directory -@file{gnu/bar/v1} of the @code{ftp.gnu.org} site. +@item rmsymlink +removes a symlink. -The directive file can be used to create currently non-existent -directory trees, as long as they are under the directory for your -package (in the example above, the package directory is @code{bar}). +@item archive +takes a file or directory offline. +@end table -If you upload a file that already exists in the FTP directory, the -original will simply be archived and replaced with the new upload. -There is no automated or online access to archived files; if you want -to retrieve or view them, please email sysadmin. +As for the directives described above, the @code{directory} and +@code{version} directives are still required, the @code{comment} +directive remains optional, and the @code{filename} directive is not +allowed. -@subheading Standalone directives +When uploaded by itself, the name of the directive file is not +important. But it must be still be signed, using @samp{gpg +--clearsign}; the resulting @file{.asc} file is what should be +uploaded. -When uploaded by itself, a directive file must contain one or more of -the directives @code{symlink}, @code{rmsymlink} or @code{archive}, in -addition to the obligatory @code{directory} and @code{version} -directives. A @code{filename} directive is not allowed, and a -@code{comment} directive remains optional. +Here's an example of the full directive file to create a +@file{foo-latest.tar.gz} symlink: + +@example +version: 1.2 +directory: foo +symlink: foo-1.1.tar.gz foo-latest.tar.gz +comment: create a symlink +@end example -If you use more than one directive, the directives are executed in the -sequence they are specified in. If a directive results in an error, -further execution of the upload is aborted. +If you include more than one directive in a standalone upload, the +directives are executed in the sequence they are specified in. If a +directive results in an error, further execution of the upload is +aborted. Removing a symbolic link (with @code{rmsymlink}) which does not exist -results in an error. However, attempting to create a symbolic link -that already exists (with @code{symlink}) is not an error. In this -case @code{symlink} behaves like the command @command{ln -s -f}: any -existing symlink is removed before creating the link. (But an -existing regular file or directory is not removed.) +results in an error. On the other hand, attempting to create a +symbolic link that already exists (with @code{symlink}) is not an +error. In this case @code{symlink} behaves like the command +@command{ln -s -f}: any existing symlink is removed before creating +the link. (But an existing regular file or directory is not replaced.) -Here are a few examples. The first removes a symlink: +Here's an example of removing a symlink, e.g., if you decide not to +maintain a @file{foo-latest} link any more: @example -version: 1.1 -directory: bar/v1 -rmsymlink: foo-latest.tgz +version: 1.2 +directory: foo +rmsymlink: foo-latest.tar.gz comment: remove a symlink @end example @noindent -Archive an old file, taking it offline: +And here's an example of archiving a file, e.g., an unintended upload: @example -version: 1.1 -directory: bar/v1 -archive: foo-1.1.tar.gz +version: 1.2 +directory: foo +archive: foo-1.1x.tar.gz comment: archive an old file; it will not be -comment: available through FTP any more. +comment: publicly available any more. @end example -@noindent -Archive an old directory (with all contents), taking it offline: - -@example -version: 1.1 -directory: bar/v1 -archive: foo -comment: archive an old directory; it and its entire -comment: contents will not be available through FTP anymore -@end example +The @code{archive} directive causes the specified items to become +inaccessible. This should only be used when it is actively bad for +them to be available, e.g., you uploaded something by mistake. -@noindent -Create a new symlink: +If all you want to do is reduce how much stuff is in your release +directory, an alternative is to email @email{sysadmin@@fsf.org} and +ask them to move old items to the @file{http://ftp.gnu.org/old-gnu/} +directory; then they will still be available. In general, however, we +recommend leaving all official releases in the main release directory. -@example -version: 1.1 -directory: bar/v1 -symlink: foo-1.2.tar.gz foo-latest.tgz -comment: create a new symlink -@end example -@noindent -Do everything at once: +@node FTP Upload Directive File - v1.1 +@subsection FTP Upload Directive File - v1.1 -@example -version: 1.1 -directory: bar/v1 -rmsymlink: foo-latest.tgz -symlink: foo-1.2.tar.gz foo-latest.tgz -archive: foo-1.1.tar.gz -comment: now do everything at once -@end example +The v1.1 protocol for uploads lacked the @code{replace} directive; +instead, file replacements were done automatically and silently +(clearly undesirable). This is the only difference between v1.2 and +v1.1. @node FTP Upload Directive File - v1.0 @subsection FTP Upload Directive File - v1.0 -Support for v1.0 uploads was phased out in May 2012; please upgrade +Support for v1.0 uploads was discontinued in May 2012; please upgrade to@tie{}v1.2. -The directive file should contain one line, excluding the clearsigned -data GPG that inserts, which specifies the final destination directory -where items (1) and (2) are to be placed. +In v1.0, the directive file contained one line, excluding the +clearsigned data GPG that inserts, which specifies the final +destination directory where items (1) and (2) are to be placed. -For example, the @file{foo.tar.gz.directive.asc} file might contain the +For example, the @file{foo-1.0.tar.gz.directive.asc} file might contain the single line: @example directory: bar/v1 @end example -This directory line indicates that @file{foo.tar.gz} and -@file{foo.tar.gz.sig} are part of package @code{bar}. If you were to +This directory line indicates that @file{foo-1.0.tar.gz} and +@file{foo-1.0.tar.gz.sig} are part of package @code{bar}. If you were to upload the triplet to @file{/incoming/ftp}, and the system can positively authenticate the signatures, then the files -@file{foo.tar.gz} and @file{foo.tar.gz.sig} will be placed in the +@file{foo-1.0.tar.gz} and @file{foo-1.0.tar.gz.sig} will be placed in the directory @file{gnu/bar/v1} of the @code{ftp.gnu.org} site. The directive file can be used to create currently non-existent @@ -1879,6 +1987,11 @@ The @t{NEWS} (@pxref{NEWS File,,, standards, GNU Coding Standards}) for the present release. @end itemize +You may find the @file{announce-gen} script useful for creating +announcements, which is available from the @file{build-aux/} directory +of the @code{gnulib} project at +@url{http://savannah.gnu.org/projects/gnulib}. + @node Web Pages @chapter Web Pages -- 2.39.5