X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fmaintain.texi;h=bef339b037cdd0d47c719bf2e789cfb9bc12ba69;hb=fa77205c7c30568a6b10ad2ebcaf785c838e2d0c;hp=6f6716f4c25186d7079516f2a295ae1f471f5cc7;hpb=88be82c11d686fc033eb832f6c8c310e6e59f457;p=gnulib.git diff --git a/doc/maintain.texi b/doc/maintain.texi index 6f6716f4c..bef339b03 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 March 22, 2006 +@set lastupdate July 9, 2006 @c %**end of header @dircategory GNU organization @@ -1077,6 +1077,8 @@ intervention needed by the system administrators. @menu * Automated Upload Registration:: * Automated Upload Procedure:: +* FTP Upload Directive File - v1.1:: +* FTP Upload Directive File - v1.0:: @end menu @@ -1118,7 +1120,7 @@ corresponding packages. @cindex uploads -Once you have registered your information, as described in the +Once you have registered your information as described in the previous section, you will be able to do unattended ftp uploads using the following procedure. @@ -1128,7 +1130,7 @@ uploaded via ftp to the host @code{ftp-upload.gnu.org}. @enumerate @item -File to distributed (e.g., @file{foo.tar.gz}). +The file to be distributed (for example, @file{foo.tar.gz}). @item Detached GPG binary signature for (1), made using @samp{gpg -b} @@ -1137,24 +1139,149 @@ Detached GPG binary signature for (1), made using @samp{gpg -b} @item A clearsigned @dfn{directive file}, made using @samp{gpg --clearsign} (for example, @file{foo.tar.gz.directive.asc}). - @end enumerate -Upload the triplet via anonymous ftp to @code{ftp-upload.gnu.org}. If -the upload is destined for @code{ftp.gnu.org}, then place the triplet -in the @file{/incoming/ftp} directory. If the upload is destined for -@code{alpha.gnu.org}, then place the triplet in the -@file{/incoming/alpha} directory. +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 +@emph{will not be processed}. + +Since v1.1 of the upload script, it is also possible to upload a +@dfn{directive file} on its own to perform certain operations on +uploaded files. @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. + +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. + +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. + +If you have difficulties processing an upload, email +@email{ftp-upload@@gnu.org}. + + +@node FTP Upload Directive File - v1.1 +@subsection FTP Upload Directive File - v1.1 + +The directive file name must end in @file{directive.asc}. + +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 'comment' directive is allowed. + +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. + +The @code{filename} directive must contain the name of the file to be +distributed (item@tie{}(1) above). + +For example, as part of an uploaded triplet, a +@file{foo.tar.gz.directive.asc} file might contain these lines (before +being gpg clearsigned): + +@example +version: 1.1 +directory: bar/v1 +filename: foo.tar.gz +comment: hello world! +@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 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. + +The directive file can be used to create currently non-existent +directory trees, as long as they are under the package directory for +your package (in the example above, that is @code{bar}). + +If you upload a file that already exists in the FTP directory, the +original will simply be archived and replaced with the new upload. + +@subheading Standalone directives + +When uploaded by itself, the 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 is optional. -Uploads are processed every five minutes. Uploads that are in -progress when the upload processing script is running are handled -properly, so do not worry about the timing of your upload. +If you use more than one directive, the directives are executed in the +sequence they are specified in. + +Here are a few examples. The first removes a symlink: + +@example +version: 1.1 +directory: bar/v1 +rmsymlink: foo-latest.tgz +comment: remove a symlink +@end example + +@noindent +Archive an old file, taking it offline: + +@example +version: 1.1 +directory: bar/v1 +archive: foo-1.1.tar.gz +comment: archive an old file - it will not be available through FTP anymore +@end example + +@noindent +Create a new symlink: + +@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: + +@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 + + +@node FTP Upload Directive File - v1.0 +@subsection FTP Upload Directive File - v1.0 + +@dfn{As of June 2006, the upload script is running in compatibility +mode, allowing uploads with either version@tie{}1.1 or +version@tie{}1.0 of the directive file syntax. Support for v1.0 +uploads will be phased out by the end of 2006, so please upgrade +to@tie{}v1.1.} 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) to be placed. +where items (1) and (2) are to be placed. -For example, the @file{foo.tar.gz.directive} file might contain the +For example, the @file{foo.tar.gz.directive.asc} file might contain the single line: @example @@ -1172,14 +1299,6 @@ The directive file can be used to create currently non-existent directory trees, as long as they are under the package directory for your package (in the example above, that is @code{bar}). -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. - -If you have difficulties processing an upload, email -@email{ftp-upload@@gnu.org}. - @node Announcements @section Announcing Releases @@ -1261,7 +1380,7 @@ so based on the contents of your @file{manual} directory. The script @command{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 +for the HTML index pages. Both are available from the Texinfo CVS sources: @format @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh}