docs/README.new-incoming

   1
   2                      Proposed New Incoming System
   3                      ============================
   4
   5 This document outlines the proposed new system for handling the
   6 Incoming directories on ftp-master and non-US.
   7
   8 The present:
   9 ------------
  10
  11   o incoming is a world writable directory
  12
  13   o incoming is available to all through http://incoming.debian.org/
  14
  15   o incoming is processed once a day by dinstall
  16
  17   o uploads in incoming must have been there > 24 hours before they
  18     are REJECTed.  If they are processed before that and have problems
  19     they will be SKIPped (with no notification to the maintainer and/or
  20     uploader).
  21
  22 The proposed future:
  23 --------------------
  24
  25   o There will be 4 incoming directories:
  26
  27      @ "unchecked"  - where uploads from Queue Daemons and maintainers
  28                       initially go
  29
  30      @ "install"    - where installable packages stay until the daily
  31                       dinstall run
  32
  33      @ "new"        - where NEW packages (and their dependents[1]) requiring
  34                       human processing go after being automatically
  35                       checked by dinstall.
  36
  37      @ "byhand"     - where BYHAND packages (and their dependents[1])
  38                       requiring human intervention go after being
  39                       automatically checked by dinstall.
  40
  41     In addition there will be 3 support directories:
  42
  43      @ "reject"     - where rejected uploads go
  44
  45      @ "done"       - where the .changes files for packages that have been
  46                       installed go.
  47
  48      @ "holding"    - a temporary working area for dinstall to hold
  49                       packages while checking them.
  50
  51   o Packages in 'unchecked' are automatically checked every 15 minutes
  52     and are either: REJECT, ACCEPT (i.e. -> 'install'), NEW or BYHAND.
  53
  54   o Only 'unchecked' is locally world-writeable.  The others are all,
  55     of course, locally world-readable but only 'install' and 'byhand'
  56     are publicly visible on http://incoming.debian.org/
  57
  58   o 'install' and 'byhand' are made available to the auto-builders so
  59      they can build out of them.
  60
  61   o 'install' is processed once a day as before.
  62
  63   o list notification and bug closures are changed to be done for
  64     ACCEPTs, not INSTALLs. Mail is sent only to the maintainer/uploader
  65     on INSTALL.
  66     [Rationale: this reduces the load both on our list server and our
  67      BTS server; it also gives people better notice of uploads to
  68      avoid duplication of work especially, for example, in the case of NMUs]
  69     [NB: see [3] for clarifications of when ACCEPT/INSTALL mails are sent]
  70
  71 Why:
  72 ----
  73
  74   o Security (no more replaceable file races)
  75   o Integrity (new http://i.d.o contains only signed (+installable) uploads[2])
  76   o Needed for crypto-in-main integration
  77   o Allows safe auto-building out of incoming
  78   o Allows previously-prohibitively-expensive checks to be added to dinstall
  79   o Much faster feedback on packages; no more 48 hour waits before
  80     finding out your package has been REJECTed.
  81
  82 What breaks:
  83 ------------
  84
  85   o uploads of large packages directly to incoming over a slow link
  86     can lead to bogus rejections.
  87
  88     * solution: Ensure the .changes file is the last file to be
  89                 uploaded (dput and dupload already do this) or upload
  90                 to a temporary directory then mv them into place with
  91                 ssh.
  92
  93   o people who upload packages but then want to retract or replace the
  94     upload.
  95
  96     * solution: mostly "Don't do that then"; i.e. test your uploads
  97       properly.  Uploads can still be replaced, simply by uploading a
  98       higher versioned replacement.  Total retraction is harder but
  99       usually only relevant for NEW packages.
 100
 101 ================================================================================
 102
 103 [1] For versions of dependents meaning: binaries compiled from the
 104     source of BYHAND or NEW uploads.  Due to katie's fascist
 105     source-must-exist checking, these binaries must be held back until
 106     the BYHAND/NEW uploads are processed.
 107
 108 [2] When this was initially written there was still at least one
 109     upload queue which will accept unsigned uploads from any
 110     source. [I've since discover it's been deactivated, but not, AFAIK
 111     because it allowed unsigned uploads.]
 112
 113 [3]
 114              --> reject
 115             /
 116            /
 117 unchecked  ---------------------------[*]-------> install ------[+]------> pool
 118            \               ^   ^
 119             |             /   /
 120             |-->   new  --   /
 121             |       |[4]    /
 122             |       V      /
 123             |--> byhand --/
 124
 125 [*] is ACCEPT and when list notification and bug closure occurs
 126 [+] is INSTALL and when maintainer/uploader notification occurs
 127
 128 [4] This is a corner case, included for completeness, ignore
 129     it. [Boring details: NEW trumps BYHAND, so it's possible for a
 130     upload with both BYHAND and NEW components to go from 'unchecked'
 131     -> 'new' -> 'byhand' -> 'install']
 132