Update premium and reserved list management docs (#380)

* Update premium and reserved list management docs

They were a little bit out of date.

docs/operational-procedures/premium-list-management.md

@@ -31,8 +31,8 @@ reconstruct a premium list .txt file from the premium list that is loaded into
 Datastore (though in principle it would be easy to do by writing a tool to do
 so), so don't lose those .txt files.
 
-An example premium list can be found at
+The nomulus repository contains an
-`java/google/registry/model/registry/config/files/premium/example.txt`.
+[example premium list file](https://github.com/google/nomulus/blob/master/core/src/main/java/google/registry/config/files/premium/example.txt).
 
 ## Creating a premium list
 
@@ -52,6 +52,9 @@ that the convention of naming premium lists after the TLD they are intended to
 be used for is enforced unless the override parameter `-o` is passed, which
 allows premium lists to be created with any name.
 
+You're not done yet! After creating the premium list you must the apply it to
+one or more TLDs (see below) for it to actually be used.
+
 ## Updating a premium list
 
 If the premium list already exists and you want to update it with new prices
@@ -66,6 +69,10 @@ Perform this command? (y/N): y
 Successfully saved premium list exampletld
 ```
 
+If this premium list is already applied to a TLD, then changes will take up to
+60 minutes to take effect (depending on how you've configured the relevant
+caching interval; 60 minutes is the default).
+
 ## Applying a premium list to a TLD
 
 Separate from the management of the contents of individual premium lists, a
@@ -92,9 +99,9 @@ all other information about a TLD). It is used as follows:
 
 ```shell
 $ nomulus -e {ENVIRONMENT} get_tld exampletld
-[ ... snip ... ]
+[ ... snip output ... ]
 premiumList=Key<?>(EntityGroupRoot("cross-tld")/PremiumList("exampletld"))
-[ ... snip ... ]
+[ ... snip output ... ]
 ```
 
 ## Listing all available premium lists
@@ -107,3 +114,22 @@ $ nomulus -e {ENVIRONMENT} list_premium_lists
 exampletld
 someotherlist
 ```
+
+## Verifying premium list updates
+
+To verify that the changes have actually been applied, you can run a domain
+check on a modified entry using the `nomulus check_domain` command and verify
+that the domain now has the correct price.
+
+```shell
+$ nomulus -e production check_domain {domain_name}
+[ ... snip output ... ]
+```
+
+ **Note that the list can be cached for up to 60 minutes, so the old value may
+still be returned for a little while**. If it is urgent that the new pricing
+changes be applied, and it's OK to potentially interrupt client connections,
+then you can use the App Engine web console to kill instances of the `default`
+service, as the cache is per-instance. Once you've killed all the existing
+instances (don't kill them all at once!), all of the newly spun up instances
+will now be using the new values you've configured.

docs/operational-procedures/reserved-list-management.md

@@ -65,14 +65,19 @@ acmecorp,RESERVED_FOR_ANCHOR_TENANT
 internaldomain,NAMESERVER_RESTRICTED,ns1.internal.tld:ns1.internal.tld
 ```
 
+# Reserved list file name format
+
 There are two types of reserved lists: Those that are intended to apply to a
-specifc TLD, and are thus prefixed with the name of the TLD followed by an
+specific TLD, and are thus prefixed with the name of the TLD followed by an
 underscore, and those that can be applied to any TLD, and are prefixed with
 `common_`. For example, a list of reserved labels on the TLD `exampletld` might
 be named `exampletld_blocked-names.txt`, whereas a similar list intended to
 apply to multiple TLDs might be named `common_blocked-names.txt`. Note that
 these naming conventions are enforced by the tooling used to create and apply
-reserved lists (see subsequent sections).
+reserved lists (see subsequent sections). The two naming patterns are thus:
+
+*   `common_list-name.txt`
+*   `tldname_list-name.txt`
 
 ## Creating a reserved list
 
@@ -82,17 +87,20 @@ purposes of this example, we are creating a common reserved list named
 "common_bad-words".
 
 ```shell
-$ nomulus -e {ENVIRONMENT} create_reserved_list -n common_bad-words \
+$ nomulus -e {ENVIRONMENT} create_reserved_list -i common_bad-words.txt
-    -i common_bad-words.txt
 [ ... snip long confirmation prompt ... ]
 Perform this command? (y/N): y
 Updated 1 entities.
 ```
 
-`-n` is the name of the reserved list to create, and `-i` is the input file
+Note that `-i` is the input file containing the list. You can optionally specify
-containing the list. Note that if `-n` is omitted, the list name is inferred
+the name of the reserved list using `-n`, but when it's omitted as above the
-from the input of the filename minus its file extension. It is recommended to
+list name is inferred from the name of the filename (minus the file extension).
-store all lists such that the filename and list name are identical.
+For ease of tracking track of things, it is recommended to store all lists such
+that the filename and list name are identical.
+
+You're not done yet! After creating the reserved list you must the apply it to
+one or more TLDs (see below) for it to actually be used.
 
 ## Updating a reserved list
 
@@ -101,15 +109,14 @@ file containing the reserved list entries, then pass it as input to the
 `update_reserved_list` command as follows:
 
 ```shell
-$ nomulus -e {ENVIRONMENT} update_reserved_list -n common_bad-words \
+$ nomulus -e {ENVIRONMENT} update_reserved_list -i common_bad-words.txt
-    -i common_bad-words.txt
 [ ... snip diff of changes to list entries ... ]
 Perform this command? (y/N): y
 Updated 1 entities.
 ```
 
 Note that, like the create command, the name of the list is inferred from the
-filename if the `-n` parameter is omitted.
+filename unless you specify the `-n` parameter (not generally recommended).
 
 ## Applying a reserved list to a TLD
 
@@ -149,9 +156,9 @@ purposes here. It is used as follows:
 
 ```shell
 $ nomulus -e {ENVIRONMENT} get_tld exampletld
-[ ... snip ... ]
+[ ... snip output ... ]
 reservedLists=[Key<?>(EntityGroupRoot("cross-tld")/ReservedList("common_bad-words"))]
-[ ... snip ... ]
+[ ... snip output ... ]
 ```
 
 ## Listing all available reserved lists
@@ -165,3 +172,22 @@ $ nomulus -e {ENVIRONMENT} list_reserved_lists
 common_bad-words
 exampletld_some-other-list
 ```
+
+## Verifying reserved list updates
+
+To verify that the changes have actually been applied, you can run a domain
+check on a modified entry using the `nomulus check_domain` command and verify
+that the domain now has the correct reservation status.
+
+```shell
+$ nomulus -e production check_domain {domain_name}
+[ ... snip output ... ]
+```
+
+ **Note that the list can be cached for up to 60 minutes, so changes may not
+take place immediately**. If it is urgent that the new changes be applied, and
+it's OK to potentially interrupt client connections, then you can use the App
+Engine web console to kill instances of the `default` service, as the cache is
+per-instance. Once you've killed all the existing instances (don't kill them all
+at once!), all of the newly spun up instances will now be using the new values
+you've configured.