Changes from Richard Jones:

- changes to the success/failure indicators used by the register.py
  command. Originally I had copied the idea of using X-PyPI-* headers
  from PEP 243. Upon advice from Greg Stein, I have switched to using
  HTTP response codes.
- clarifications to Roles
- added PKG-INFO upload interface

pep-0301.txt

@@ -99,7 +99,7 @@ The web interface implements the following commands/interfaces:
   plain text.  The "url" (or "home_page") field is hyperlinked.
 
 **submit**
-  Accepts a POST form submission of metadata about a package.  The
+  Accepts a POST submission of metadata about a package.  The
   "name" and "version" fields are mandatory, as they uniquely identify
   an entry in the index.  **Submit** will automatically determine
   whether to create a new entry or updating an existing entry.  The
@@ -111,6 +111,10 @@ The web interface implements the following commands/interfaces:
   There will also be a submit/edit form that will allow manual submission
   and updating for those who do not use Distutils.
 
+**submit_pkg_info**
+  Accepts a POST submission of a PKG-INFO file and performs the same
+  function as the **submit** interface.
+
 **user**
   Registers a new user with the index.  Requires username, password and
   email address.  Passwords will be stored in the index database as SHA
@@ -128,22 +132,20 @@ The web interface implements the following commands/interfaces:
      to visit to confirm registration with a random one-time key, and
   3. User visits URL with the key and confirms registration.
 
-  Several user Roles will exist:
-
-  Admin
-    Can assign Owner Role - they decide who may submit for a given
-    package name.
+  Several user Roles will exist, generally revolving around a
+  particular package name:
 
   Owner
     Owns a package name, may assign Maintainer Role for that name.  The
-    first user to register information about a package is deemed owner
+    first user to register information about a package is deemed Owner
     of the package name.  The Admin user may change this if necessary.
+    May submit updates for the package name.
 
   Maintainer
-    Can submit and update info for a particular package name
+    Can submit and update info for a particular package name.
 
-  Manual (through-the-web) user registration is also available through
-  an HTML form.
+  Admin
+    Can assign Owner Role and edit user details.
 
 **roles**
   An interface for changing user Role assignments.
@@ -155,6 +157,19 @@ The web interface implements the following commands/interfaces:
 The **submit** command will require HTTP Basic authentication,
 preferably over an HTTPS connection.
 
+The server interface will indicate success or failure of the commands
+through a subset of the standard HTTP response codes:
+
+===== ============== ================================================
+Code  Meaning        Register command implications
+===== ============== ================================================
+200   OK             Everything worked just fine
+400   Bad request    Data provided for submission was malformed
+401   Unauthorised   The username or password supplied were incorrect
+403   Forbidden      User does not have permission to update the
+                     package information (not Owner or Maintainer)
+===== ============== ================================================
+
 
 Distutils *register* Command
 ----------------------------
@@ -183,16 +198,6 @@ as usual and report any errors it would have reported during a normal
 submission.  This is useful for verifying correctness of Trove
 discriminators.
 
-The index server will return custom headers (inspired by PEP 243)
-which the *register* command will use to give feedback to the user:
-
-**X-Pypi-Status**
-  Either "success" or "fail".
-
-**X-Pypi-Reason**
-  A description of the reason for failure, or additional information
-  in the case of a success.
-
 
 Distutils Trove Categorisation
 ------------------------------
@@ -280,6 +285,22 @@ initial prototype had 45 visitors (not including myself), two of whom
 used the *register* command to submit package information.
 
 
+Rejected Proposals
+==================
+
+Originally, the index server was to return custom headers (inspired by
+PEP 243):
+
+**X-Pypi-Status**
+  Either "success" or "fail".
+
+**X-Pypi-Reason**
+  A description of the reason for failure, or additional information
+  in the case of a success.
+
+However, it has been pointed out [8]_ that this is a bad scheme to use.
+
+
 References
 ==========
 
@@ -304,6 +325,9 @@ References
 .. [7] PEP 262, A Database of Installed Python Packages
    (http://www.python.org/peps/pep-0262.html)
 
+.. [8] [PEP243] upload status is bogus
+   (http://mail.python.org/pipermail/distutils-sig/2001-March/002262.html)
+
 
 Copyright
 =========
@@ -319,6 +343,9 @@ and feedback during initial drafting.
 
 A.M. Kuchling for support including hosting the second prototype.
 
+Greg Stein for recommending that the register command interpret the
+HTTP response codes rather than custom X-PyPI-* headers.
+
 The many participants of the Distutils and Catalog SIGs for their
 ideas over the years.
 
@@ -330,3 +357,4 @@ ideas over the years.
    sentence-end-double-space: t
    fill-column: 70
    End:
+