Merge pull request python#37 from joshuagl/joshuagl/bins

Point out that changes to number of bins are transparent to the client

Author: lukpueh

pep-0458.txt

@@ -451,14 +451,32 @@ Based on our findings as of the time this document was updated for implementatio
 (Oct 7 2019), PyPI SHOULD split all targets in the *bins* role by delegating
 them to 16,384 *bin-n* roles. Each *bin-n* role would sign for the PyPI targets whose
 hashes fall into that bin (see Figure 2).  It was found__
-that this number of bins would result in a 12-17% metadata overhead for
-returning users, and a 148% overhead for new users who are installing
-pip for the first time.
+that this number of bins would result in a 12-17% metadata overhead
+(relative to the average size of downloaded packages) for returning users
+(assuming 256-byte target filenames for all packages), and a 148% overhead
+for new users who are installing pip for the first time.
 
 __ https://docs.google.com/spreadsheets/d/11_XkeHrf4GdhMYVqpYWsug6JNz5ZK6HvvmDZX0__K2I/edit?usp=sharing
 
-While it is possible to make TUF metadata more compact by representing it in a
-binary format, as opposed to the JSON text format, a sufficiently large
+This number of bins SHOULD increase when the metadata overhead for returning
+users exceeds 50%. Presently, this SHOULD happen when the number of targets
+increase at least 4x from over 2M to nearly 9M, at which point the metadata
+overhead for returning and new users would be around 49-54% (assuming 256-byte
+target filenames for all packages) and 185% respectively, assuming that the
+number of bins stay fixed. If the number of bins is increased, then the cost
+for all users would effectively be the cost for new users, because their cost
+would be dominated by the (once-in-a-while) cost of downloading the large
+number of delegations in the `bins` metadata. If the cost for new users
+should prove to be too much, then this subject SHOULD be revisited before
+that happens.
+
+Note that changes to the number of bins on the server are transparent to the
+client.  The package manager will be required to download a fresh set of
+metadata, as though it were a new user, but this operation will not require any
+explicit code logic or user interaction in order to do so.
+
+It is possible to make TUF metadata more compact by representing it in a binary
+format, as opposed to the JSON text format.  Nevertheless, a sufficiently large
 number of projects and distributions will introduce scalability challenges at
 some point, and therefore the *bins* role will still need delegations (as
 outlined in figure 2) in order to address the problem.  The JSON format is an