2004-02-27 Martin Michlmayr <tbm@cyrius.com> * docs/README.config: lots of updates...

diff --git a/docs/README.config b/docs/README.config
index 80a1010d0ec9cff5202a663f8ba773cfe77d01e1..087bf23f70f5afaeb756cf161eedd7707397e62f 100644 (file)
--- a/docs/README.config
+++ b/docs/README.config
@@ -13,8 +13,14 @@ Essential.  List of database details, e.g.
 |   Port -1;
 | };
 
 |   Port -1;
 | };
 

-If the database is local, Host should be blank.  If the port is the
-default (5432), it should be set to -1.
+Name (required): The name of the PostgreSQL database which has been created
+for katie.
+
+Host (required): The name of the host on which the database is located.  If
+the database is local, Host should be blank.
+
+Port (required): The port of the database.  If the port is the default
+value (5432), this option should be set to -1.

 
 ================================================================================
 
 
 ================================================================================
 


@@ -33,12 +39,11 @@ Mandatory.  List of directory locations, e.g.
 |   Lists "/org/ftp.debian.org/database/dists/";
 |   Log "/org/ftp.debian.org/log/";
 |   Morgue "/org/ftp.debian.org/morgue/";
 |   Lists "/org/ftp.debian.org/database/dists/";
 |   Log "/org/ftp.debian.org/log/";
 |   Morgue "/org/ftp.debian.org/morgue/";

-|   Override "/org/ftp.debian.org/scripts/override/";
+|   MorgueReject "reject";

 |   AcceptedAutoBuild "/org/incoming.debian.org/buildd/";
 |   UrgencyLog "/org/ftp.debian.org/testing/urgencies/";
 |   Queue
 |   {  
 |   AcceptedAutoBuild "/org/incoming.debian.org/buildd/";
 |   UrgencyLog "/org/ftp.debian.org/testing/urgencies/";
 |   Queue
 |   {  

-|     Root "/org/ftp.debian.org/queue/";

 |     Accepted "/org/ftp.debian.org/queue/accepted/";
 |     Byhand "/org/ftp.debian.org/queue/byhand/";
 |     Done "/org/ftp.debian.org/queue/done/";
 |     Accepted "/org/ftp.debian.org/queue/accepted/";
 |     Byhand "/org/ftp.debian.org/queue/byhand/";
 |     Done "/org/ftp.debian.org/queue/done/";


@@ -49,6 +54,47 @@ Mandatory.  List of directory locations, e.g.
 |   };
 | };
 
 |   };
 | };
 

+Root (required): Specifies the path of the root of the FTP archive.
+
+Pool (required): This variable specifies the path of the pool directory.
+Debian packages will be placed in the pool by kelly after they have been
+accepted by jennifer.
+
+Templates (required): katie sends various mails and uses templates from
+this directory.
+
+PoolRoot (required): This variable specifies the basename of the pool
+directory.
+
+Override (optional): This directory optionally stores override files (used
+by denise).
+
+Lists (optional): This directory holds file lists used by apt-ftparchive to
+generate Packages and Sources files (used by jenna).
+
+Log (required): Log files are put in this directory.
+
+Morgue (required): Removed files are moved there.  The morgue has various
+sub-directories, including (optionally) those defined by
+Shania::MorgueSubDir and Rhona::MorgueSubDir.
+
+MorgueReject (required): if katie cannot move a rejected package to
+Dir::Queue::Reject, it will try to move it to the Dir::MorgueReject
+directory located under Dir::Morgue.
+
+AcceptedAutoBuild (optional): This variable is only relevant if any suites
+are to be auto built, i.e. if Dinstall::AcceptedAutoBuildSuites has any
+values.
+
+UrgencyLog (optional): If this directory is specified, kelly will store the
+urgency value of each upload.  This is mainly used for britney (the testing
+script).
+
+Queue (required): This sub-tree defines important directories for the
+incoming queue.  The following variables have to be set: Accepted, Byhand
+Done, Holding, New, Reject, Unchecked.  An explanation of the function of
+these directores can be found in README.new-incoming.
+

 ================================================================================
 
 Suite
 ================================================================================
 
 Suite


@@ -62,13 +108,13 @@ Mandatory.  List of all suites, e.g.
 |   {
 |      Components 
 |      {
 |   {
 |      Components 
 |      {

-|        main "";
+|        main;

 |      };
 |      Architectures 
 |      {
 |      };
 |      Architectures 
 |      {

-|        "source" ""; 
-|        "all" "";
-|        "i386" "";
+|        source; 
+|        all;
+|        i386;

 |      };
 |      Announce "debian-devel-changes@lists.debian.org";
 |      Origin "Debian";
 |      };
 |      Announce "debian-devel-changes@lists.debian.org";
 |      Origin "Debian";


@@ -79,23 +125,30 @@ Mandatory.  List of all suites, e.g.
 |   };
 | };
 
 |   };
 | };
 

-Announce controls where "Installed foo" mails are sent; leave empty to
-not send any.  CodeName, Origin and Description are used by ziyi and
-put in the Release files.  OverrideCodeName is used by Denise.
-Priority determines which suite is used for the Maintainers file as
-generated by charisma/da_mkmaintainers (highest wins).
+Announce (optional): controls where "Installed foo" mails are sent.
+
+CodeName, Origin and Description (optional): This settings are used by ziyi
+and put in the Release files.
+
+OverrideCodeName (optional): used by Denise.
+
+Priority (optional) determines which suite is used for the Maintainers file
+as generated by charisma/da_mkmaintainers (highest wins).

 
 

-If CopyChanges is present it should be a path into the archive
-(i.e. "Dir::RootDir"); any upload targeted for a suite with this
-config option present will have the .changes file copied into that
-path.
+CopyChanges (optional): if this variable is present it should be a path
+into the archive (i.e. "Dir::RootDir"); any upload targeted for a suite
+with this config option present will have the .changes file copied into
+that path.

 
 

-If CopyKatie is present it should be an absolute path; any upload
-targeted for a suite with this config option present will have the
-.katie file copied into that path.  This option is similar to
-CopyChanges and will most often be used with it; they're seperate
-because .changes files are mirrored and .katie files aren't, so the
-paths will usually be different.
+CopyKatie (optional): if this is present it should be an absolute path; any
+upload targeted for a suite with this config option present will have the
+.katie file copied into that path.  This option is similar to CopyChanges
+and will most often be used with it; they're seperate because .changes
+files are mirrored and .katie files aren't, so the paths will usually be
+different.
+
+There are more optional variables, such as VersionChecks.  Please see
+katie.conf for examples.

 
 ================================================================================
 
 
 ================================================================================
 


@@ -146,6 +199,7 @@ Mandatory.  List of dinstall options, e.g.:
 |    PGPKeyring "/org/keyring.debian.org/keyrings/debian-keyring.pgp";
 |    GPGKeyring "/org/keyring.debian.org/keyrings/debian-keyring.gpg";
 |    SigningKeyring "/org/ftp.debian.org/s3kr1t/dot-gnupg/secring.gpg";
 |    PGPKeyring "/org/keyring.debian.org/keyrings/debian-keyring.pgp";
 |    GPGKeyring "/org/keyring.debian.org/keyrings/debian-keyring.gpg";
 |    SigningKeyring "/org/ftp.debian.org/s3kr1t/dot-gnupg/secring.gpg";

+|    SendmailCommand "/usr/sbin/sendmail -odq -oi -t";

 |    MyEmailAddress "Debian Installer <installer@ftp-master.debian.org>";
 |    MyAdminAddress "ftpmaster@debian.org";
 |    MyHost "debian.org";  // used for generating user@my_host addresses in e.g. manual_reject()
 |    MyEmailAddress "Debian Installer <installer@ftp-master.debian.org>";
 |    MyAdminAddress "ftpmaster@debian.org";
 |    MyHost "debian.org";  // used for generating user@my_host addresses in e.g. manual_reject()


@@ -156,66 +210,80 @@ Mandatory.  List of dinstall options, e.g.:
 |    LockFile "/org/ftp.debian.org/katie/lock";
 |    Bcc "archive@ftp-master.debian.org";
 |    GroupOverrideFilename "override.group-maint";
 |    LockFile "/org/ftp.debian.org/katie/lock";
 |    Bcc "archive@ftp-master.debian.org";
 |    GroupOverrideFilename "override.group-maint";

-|    FutureTimeTravelGrace "8640"; // 6 hours
+|    FutureTimeTravelGrace 28800; // 8 hours

 |    PastCutoffYear "1984";
 |    PastCutoffYear "1984";

-|    BXANotify 0;
+|    BXANotify "false";
+|    AcceptedAutoBuildSuites
+|    {
+|      unstable;
+|    };

 | };
 
 | };
 

-PGPKeyring and GPGKeyring are mandatory fields which are filenames of
-the PGP and GnuPG keyrings to be used by katie respectively.
+PGPKeyring and GPGKeyring (required): filenames of the PGP and GnuPG
+keyrings to be used by katie respectively.
+
+SigningKeyring (optional): this is the private keyring used by ziyi.
+
+SendmailCommand (required): command to call the MTA.

 
 

-SigningKeyring is the private keyring used by ziyi.
+MyEmailAddress (required): this is used as the From: line for sending mails
+as a script/daemon.

 
 

-MyEmailAddress is used as the From: line for sending mails as a
-script/daemon.  MyAdminAddress is used as a contact address in mails.
+MyAdminAddress (required): used as a contact address in mails.

 
 

-MyDistribution is used in emails sent out by katie and others.
+MyDistribution (required): this variable is used in emails sent out by
+katie and others.  It should indicate the name of the distribution.

 
 

-BugServer is used by katie and melanie when closing bugs.
+BugServer (required): is used by katie and melanie when closing bugs.

 
 

-PackagesServer is used by melanie when carbon-copying a bug close mail
-to a package maintainer.
+PackagesServer (requried): used by melanie when carbon-copying a bug close
+mail to a package maintainer.

 
 

-TrackingServer is used by katie and melanie to send messages for the
-maintainer also to an alias for people tracking a specific source
+TrackingServer (optional): used by katie and melanie to send messages for
+the maintainer also to an alias for people tracking a specific source

 package.
 
 package.
 

-LockFile is a mandatory field and contains the filename of the
-lockfile used by dinstall when in action mode (i.e. not using
--n/--no-action).
+LockFile (required): contains the filename of the lockfile used by dinstall
+when in action mode (i.e. not using -n/--no-action).
+
+All sent mail is blind carbon copied to the email address in Bcc if it's
+not blank.
+
+GroupOverrideFilename (optional): this is the override file which contains
+the list of email addresses which, if part of the Maintainer field, cause
+uploads to always be treated as maintainer uploads.

 
 

-All sent mail is blind carbon copied to the email
-address in Bcc if it's not blank.  
+FutureTimeTravelGrace (required): specifies how many seconds into the
+future timestamps are allowed to be inside a deb before being rejected.

 
 

-GroupOverrideFilename, if non-blank, is the override file which
-contains the list of email addresses which, if part of the Maintainer
-field, cause uploads to always be treated as maintainer uploads.
+PastCutoffYear (required): specifies the cut-off year which is used when
+deciding whether or not to reject packages based on the file timestamp.

 
 

-FutureTimeTravelGrace specifies how many seconds into the future
-timestamps are allowed to be inside a deb before being rejected.
-PastCutoffYear specifies the cut-off year which is used when deciding
-whether or not to reject packages based on the file timestamp.
+BXANotify (optional): a boolean (default: no); if true (Debian-specific)
+BXA notification is sent.  The template for the BXA notification is located
+in Dir::Templates/lisa.bxa_notification and should be changed if this
+option is set.

 
 

-BXANotify is a boolean; if true (Debian-specfic) BXA notification is
-sent.
+OverrideDisparityCheck (optional): a boolean (default: no); if true,
+jennifer compares an uploads section/priority with the overrides and whines
+at the maintainer if they differ.

 
 

-OverrideDisparityCheck is a boolean; if true, jennifer compares an
-uploads section/priority with the overrides and whines at the
-maintainer if they differ.
+CloseBugs (optional): a boolean (default: no); if true the automated bug
+closing feature of dinstall is activated.

 
 

-CloseBugs is a boolean; if true the automated bug closing feature of
-dinstall is activated.
+AcceptedAutoBuildSuites (optional): a list of suites which should be auto
+build.

 
 SpecialAcceptedAutoBuild is a boolean; if true it activates support
 for auto-building from accepted.
 
 
 SpecialAcceptedAutoBuild is a boolean; if true it activates support
 for auto-building from accepted.
 

-OverrideMaintainer can be used to globally override the
+OverrideMaintainer (optional): be used to globally override the

 __MAINTAINER_TO__ and __MAINTAINER_FROM__ variables in template mails.
 Use with caution.
 
 __MAINTAINER_TO__ and __MAINTAINER_FROM__ variables in template mails.
 Use with caution.
 

-SkipTime is an integer value which is the number of seconds that a
-file must be older than (via it's last modified timestamp) before
-jennifer will REJECT rather than SKIP the package.
+SkipTime (required): an integer value which is the number of seconds that a
+file must be older than (via it's last modified timestamp) before jennifer
+will REJECT rather than SKIP the package.

 
 ================================================================================
 
 
 ================================================================================
 


@@ -234,9 +302,9 @@ Mandatory.  List of all archives, e.g.
 |   };
 | };
 
 |   };
 | };
 

-OriginServer and PrimaryMirror are mandatory and are used melanie's
-bug closing mail templates.  The host name and it's OriginServer and
-Description are part of the SQL database in the 'archive' table.
+OriginServer and PrimaryMirror (required): used melanie's bug closing mail
+templates.  The host name and it's OriginServer and Description are part of
+the SQL database in the 'archive' table.

 
 ================================================================================
 
 
 ================================================================================
 


@@ -253,7 +321,7 @@ Mandatory.  List of all architectures, e.g.
 | };
 
 Both values go into the SQL database's 'architecture' table.
 | };
 
 Both values go into the SQL database's 'architecture' table.

-Description is currently unused.
+The description is currently unused.

 
 ================================================================================
 
 
 ================================================================================
 


@@ -283,7 +351,7 @@ Mandatory.  List of all valid sections, e.g.
 
 | Section
 | {
 
 | Section
 | {

-|   base "";
+|   base;

 | };
 
 The section goes into the 'section' table in SQL database.
 | };
 
 The section goes into the 'section' table in SQL database.


@@ -346,12 +414,38 @@ the Components section 'legacy-mixed' are assumed to mix all
 components into one location.  The Archive and Type sections go into
 the SQL database's 'location' table.
 
 components into one location.  The Archive and Type sections go into
 the SQL database's 'location' table.
 

+Note that the archive value specified here must correspond to one defined
+in Archive.
+

 [Note: yes, this is horrible, it dates back to the original `import
        the existent archive into the SQL Database' script (neve) and
        isn't otherwise used.  It should be revisted at some stage.]
 
 ================================================================================
 
 [Note: yes, this is horrible, it dates back to the original `import
        the existent archive into the SQL Database' script (neve) and
        isn't otherwise used.  It should be revisted at some stage.]
 
 ================================================================================
 

+Urgency
+-------
+
+Mandatory.
+
+| Urgency
+| {
+|   Default "low";
+|   Valid
+|   {
+|     low;
+|     medium;
+|     high;
+|     emergency;
+|     critical;
+|   };
+| };
+
+This defines the valid and default urgency of an upload.  If a package is
+uploaded with an urgency not listed here, it will be rejected.
+
+================================================================================
+

 -- 
 James Troup <james@nocrew.org>, Horsforth, Leeds
 Wed, 26 Sep 2001 03:20:39 +0100
 -- 
 James Troup <james@nocrew.org>, Horsforth, Leeds
 Wed, 26 Sep 2001 03:20:39 +0100

diff --git a/docs/README.first b/docs/README.first
index 5a526ac8a81f207916492cbe6d4f5adc31968620..1f5d23a4d6ae97d71917aa1f21c2ba71eb6bd56d 100644 (file)
--- a/docs/README.first
+++ b/docs/README.first
@@ -101,10 +101,24 @@ o katie - common code used by lisa, jennifer, kelly and others
 
 [Very incomplete - FIXME]
 
 
 [Very incomplete - FIXME]
 

-o Write your own katie.conf and apt.conf files
-o Run rose
+o Write your own katie.conf and apt.conf files.  katie looks for those
+  config files in /etc/katie/.  /etc/katie/katie.conf can define
+  alternative configuration files with Config::host::KatieConfig and
+  Config::host::AptConfig (where "host" is the fully qualified domain
+  name of your machine).
+o Create a PostgreSQL database on the host given in katie.conf's DB::Host
+  with the name specified in DB::Name.
+o Run rose: this will create all directories which are specified in
+  katie.conf and apt.conf.

 o If you have an existing archive:
    * Run neve
   otherwise:
 o If you have an existing archive:
    * Run neve
   otherwise:

-   * Run alyson
+   * Create the table structure.  init_pool.sql contains all SQL statements
+     which are needed for this.  After changing all occurences of "projectb"
+     to the name of your database (as defined in DB::Name) you can run:
+         psql DB::Name < init_pool.sql
+   * Run alyson: it will populate your database with the values from
+     katie.conf and apt.conf.
+   * Copy all templates from the "templates" directory to to the directory
+     specified in Dir::Templates, and adapt them to your distribution.

 
 

diff --git a/katie.conf b/katie.conf
index f49dd574ec87cb0c286c2b50e96d796c0dc6ad29..1098c73853d2a2150a68251cef3f42e95dd3de25 100644 (file)
--- a/katie.conf
+++ b/katie.conf
@@ -16,7 +16,7 @@ Dinstall
    LockFile "/org/ftp.debian.org/katie/lock";
    Bcc "archive@ftp-master.debian.org";
    GroupOverrideFilename "override.group-maint";
    LockFile "/org/ftp.debian.org/katie/lock";
    Bcc "archive@ftp-master.debian.org";
    GroupOverrideFilename "override.group-maint";

-   FutureTimeTravelGrace 28800; // 6 hours
+   FutureTimeTravelGrace 28800; // 8 hours

    PastCutoffYear "1984";
    SkipTime 300;
    BXANotify "true";
    PastCutoffYear "1984";
    SkipTime 300;
    BXANotify "true";


@@ -409,7 +409,6 @@ Dir
   UrgencyLog "/org/ftp.debian.org/testing/urgencies/";
   Queue
   {
   UrgencyLog "/org/ftp.debian.org/testing/urgencies/";
   Queue
   {

-    Root "/org/ftp.debian.org/queue/";

     Accepted "/org/ftp.debian.org/queue/accepted/";
     Byhand "/org/ftp.debian.org/queue/byhand/";
     Done "/org/ftp.debian.org/queue/done/";
     Accepted "/org/ftp.debian.org/queue/accepted/";
     Byhand "/org/ftp.debian.org/queue/byhand/";
     Done "/org/ftp.debian.org/queue/done/";

diff --git a/katie.conf-non-US b/katie.conf-non-US
index 490e6eec7a32947d316f963a7752a23a8b34ea0d..24bfd1c60412cdefe070cbda2436424c37e5fac2 100644 (file)
--- a/katie.conf-non-US
+++ b/katie.conf-non-US
@@ -16,7 +16,7 @@ Dinstall
    LockFile "/org/non-us.debian.org/katie/lock";
    Bcc "archive@ftp-master.debian.org";
    GroupOverrideFilename "override.group-maint";
    LockFile "/org/non-us.debian.org/katie/lock";
    Bcc "archive@ftp-master.debian.org";
    GroupOverrideFilename "override.group-maint";

-   FutureTimeTravelGrace 28800; // 6 hours
+   FutureTimeTravelGrace 28800; // 8 hours

    PastCutoffYear "1984";
    SkipTime 300;
    CloseBugs "true";
    PastCutoffYear "1984";
    SkipTime 300;
    CloseBugs "true";


@@ -333,7 +333,6 @@ Dir
   UrgencyLog "/org/non-us.debian.org/testing/";
   Queue
   {
   UrgencyLog "/org/non-us.debian.org/testing/";
   Queue
   {

-    Root "/org/non-us.debian.org/queue/";

     Accepted "/org/non-us.debian.org/queue/accepted/";
     Byhand "/org/non-us.debian.org/queue/byhand/";
     Done "/org/non-us.debian.org/queue/done/";
     Accepted "/org/non-us.debian.org/queue/accepted/";
     Byhand "/org/non-us.debian.org/queue/byhand/";
     Done "/org/non-us.debian.org/queue/done/";

diff --git a/katie.conf-security b/katie.conf-security
index c6a156e42e1da48f4d341a9c7907f107660bfdce..cb4b37d5d777696e2fc89acba09e3afacf7f9676 100644 (file)
--- a/katie.conf-security
+++ b/katie.conf-security
@@ -15,7 +15,7 @@ Dinstall
    LockFile "/org/security.debian.org/katie/lock";
    Bcc "archive@ftp-master.debian.org";
    // GroupOverrideFilename "override.group-maint";
    LockFile "/org/security.debian.org/katie/lock";
    Bcc "archive@ftp-master.debian.org";
    // GroupOverrideFilename "override.group-maint";

-   FutureTimeTravelGrace 28800; // 6 hours
+   FutureTimeTravelGrace 28800; // 8 hours

    PastCutoffYear "1984";
    SkipTime 300;
    CloseBugs "false";
    PastCutoffYear "1984";
    SkipTime 300;
    CloseBugs "false";


@@ -197,7 +197,6 @@ Dir
   AcceptedAutoBuild "/org/security.debian.org/buildd/";
   Queue
   {
   AcceptedAutoBuild "/org/security.debian.org/buildd/";
   Queue
   {

-    Root "/org/security.debian.org/queue/";

     Accepted "/org/security.debian.org/queue/accepted/";
     Byhand "/org/security.debian.org/queue/byhand/";
     Done "/org/security.debian.org/queue/done/";
     Accepted "/org/security.debian.org/queue/accepted/";
     Byhand "/org/security.debian.org/queue/byhand/";
     Done "/org/security.debian.org/queue/done/";