Merge pull request #354 from ritaf-ORM/patch-13

Rita edits ch 23

chapter_23_debugging_prod.asciidoc

@@ -7,7 +7,7 @@ This chapter has been recently updated to Django 5, Ansible+Docker, etc.
 
 It all works on my machine, as they say!
 Let me know if you run into anything strange.
-Feedback and suggestions of any kind appreciated, as always.
+Feedback and suggestions of any kind are appreciated, as always.
 
 *******************************************************************************
 
@@ -25,7 +25,7 @@ Let's see how that works against our staging server and Docker.
 Remember the deployment checklist from <<chapter_18_second_deploy>>?
 Let's see if it can't come in useful today!
 
-First we rebuild and start our Docker container locally,
+First, we rebuild and start our Docker container locally,
 on port 8888:
 
 [subs="specialcharacters,quotes"]
@@ -176,7 +176,7 @@ $ *echo $EMAIL_PASSWORD*
 $ *export EMAIL_PASSWORD="yoursekritpasswordhere"*
 ----
 
-Now let's pass that env var thru to our docker container using one more `-e` flag,
+Now let's pass that env var through to our docker container using one more `-e` flag,
 this one fishing the env var out of the shell we're in:
 
 
@@ -222,6 +222,7 @@ But our FT is saying it can't see any emails appearing in `mail.outbox`.
 
 ==== `mail.outbox` Won't Work Outside Django's Test Environment
 
+// RITA: The reason what? Please clarify. "The reason why our FT can't see any emails is because `mail.outbox` is a local..."
 The reason is that `mail.outbox` is a local, in-memory variable in Django,
 so that's only going to work when our tests and our server are running in the same process,
 like they do with unit tests or with `LiveServerTestCase` FTs.
@@ -239,13 +240,14 @@ that the server sends, in our tests against Docker
 
 This is a point at which we have to explore some tradeoffs.
 There are a few different ways we could test this:
+// RITA: What do you mean by "this"? Please clarify.
 
 1. We could build a "real" end-to-end test, and have our tests
    log in to an email server, and retrieve the email from there.
-   That's what I did in the first and second edition.
+   That's what I did in the first and second editions of this book.
 
 2. You can use a service like Mailinator or Mailsac,
-   which give you an email account to send to,
+   which gives you an email account to send to,
    and some APIs for checking what mail has been delivered.
 
 3. We can use an alternative, fake email backend,
@@ -254,12 +256,12 @@ There are a few different ways we could test this:
    for example,
    and we can inspect them there.
 
-4. Or we could give up on testing email on the server.
+4. We could give up on testing email on the server.
    If we have a minimal smoke test that the server _can_ send emails,
    then we don't need to test that they are _actually_ delivered.
 
 
-But let's lay out some of the pros + cons:
+But let's lay out some of the pros and cons:
 
 
 .Testing Strategy Tradeoffs
@@ -272,14 +274,16 @@ But let's lay out some of the pros + cons:
 | Give up on testing email on the server/Docker | Fast, simple | Less confidence that things work "for real"
 |=======
 
+// RITA: For narrative clarity, repeat what "this" refers to here.
 This is a common problem in testing integration with external systems,
 how far should we go?  How realistic should we make our tests?
 
 In this case, I'm going to suggest we go for the last option,
 which is not to test email sending on the server or in Docker.
 
+// RITA: Although the sentence has a lot of your voice, I don't think mentioning your birthday is necessary. The reader probably has no idea how old you are. It would be enough to say that email has been around for a while now.
 Email itself is a well-understood protocol
-(reader, it's been around since _before I was born_, and that's a whiles ago now)
+(reader, it's been around since _before I was born_, and that's a while ago now)
 and Django has supported sending email for more than a decade,
 so I think we can afford to say, in this case,
 that the costs of building testing tools for email outweigh the benefits.
@@ -370,7 +374,7 @@ EMAIL_PASSWORD={{ email_password }}
 ----
 ====
 
-and now we add the line to the ansible deploy playbook
+And now we add the line to the ansible deploy playbook
 that looks up EMAIL_PASSWORD in our local environment:
 
 
@@ -458,7 +462,7 @@ FAILED (errors=1)
 
 
 
-It's because our test utility function `create_pre_authenticated_session()`
+It fails because our test utility function `create_pre_authenticated_session()`
 only acts on the local database.
 Let's find out how our tests can manage the database on the server.
 
@@ -710,7 +714,7 @@ Does that all make sense?
 Perhaps a little ascii-art diagram will help:
 
 
-
+// RITA: Shall we turn these into proper diagrams? Is there a particular reason why these are shown as ascii-art? I know that's how they were shown in the previous edition. 
 ===== Locally:
 
 [role="skipme small-code"]
@@ -770,7 +774,7 @@ or on a server, would be to talk directly to the DB
 Since we're using SQLite, that involves writing to the file directly,
 This can be fiddly to get right, because when we're running inside Django's
 test runner, Django takes over test database creation,
-so you end up having to write raw SQL and managing your connections to the database directly.
+so you end up having to write raw SQL and manage your connections to the database directly.
 
 There are also some tricky interactions with the filesystem mounts and Docker,
 as well as needing to have the SECRET_KEY env var set to the same value as on the server.
@@ -784,6 +788,7 @@ but it's still fiddly to get right and usually requires writing your own SQL.
 
 === Testing the Management Command
 
+// RITA: Give this first sentence a tiny bit more context. Let's see if what works?
 In any case, let's see if it works.
 First, locally, to check that we didn't break anything:
 
@@ -954,7 +959,7 @@ and make it so they use different keypairs for authentication, with different pa
 
 This is similarly dangerous territory to running tests against clones of production data.
 I have a little story about accidentally sending thousands of duplicate invoices to clients
-in <<data-migrations-appendix>>. LFMF.
+in <<data-migrations-appendix>>.
 
 *******************************************************************************