Merge remote-tracking branch 'atlas/main'

hjwp · hjwp · commit 750a121f412b · 2025-10-27T16:48:45.000Z
diff --git a/acknowledgments.asciidoc b/acknowledgments.asciidoc
@@ -133,7 +133,7 @@ Tom Nguyen,
 rokbot,
 Nikita Durne,
 and to anyone I've missed off this list,
-my sincere apologies, ping me and i'll add you,
+my sincere apologies, ping me and I'll add you,
 and thank you thank you once again.
 
 
diff --git a/appendix_X_what_to_do_next.asciidoc b/appendix_X_what_to_do_next.asciidoc
@@ -106,7 +106,7 @@ so if the other person adds an item to the list, you see it immediately?
 A persistent connection between client and server using websockets
 is the way to get this to work.
 
-Check out Django's aysnc features see if you can them to implement dynamic notifications.
+Check out Django's async features and see if you can use them to implement dynamic notifications.
 
 To test it, you'll need two browser instances
 (like we used for the list sharing tests),
diff --git a/appendix_purist_unit_tests.asciidoc b/appendix_purist_unit_tests.asciidoc
@@ -877,7 +877,7 @@ we can do better.
 Keep Listening to Your Tests: Removing ORM Code from Our Application
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-((("Object-Relational Mapper (ORM)")))Again, these tests are trying to tell us something:  the Django ORM
+((("object-relational mapper (ORM)")))Again, these tests are trying to tell us something:  the Django ORM
 is hard to mock out, and our form class needs to know too much about
 how it works.  Programming by wishful thinking again, what would
 be a simpler API that our form could use?  How about something like
@@ -2077,7 +2077,7 @@ the most hard work
 
 
 Decoupling our application from ORM code::
-    ((("Object-Relational Mapper (ORM)")))One
+    ((("object-relational mapper (ORM)")))One
 of the consequences of striving to write isolated tests is that we
     find ourselves forced to remove ORM code from places like views and forms,
     by hiding it behind helper functions or methods.  This can be beneficial in
diff --git a/atlas.json b/atlas.json
@@ -52,7 +52,7 @@
   ],
   "formats": {
     "pdf": {
-      "version": "web",
+      "version": "print",
       "toc": true,
       "index": true,
       "antennahouse_version": "AHFormatterV71_64-MR2",
diff --git a/chapter_03_unit_test_first_view.asciidoc b/chapter_03_unit_test_first_view.asciidoc
@@ -257,7 +257,7 @@ the `-m` flag lets you pass in a commit message at the command line,
 so you don't need to use an editor.
 It's up to you to pick the way you like to use the Git command line;
 I'll just show you the main ones I've seen used.
-For me, the main big of VCS hygiene is:
+For me, the key rule of VCS hygiene is:
 _make sure you always review what you're about to commit before you do it_.
 
 [[django-mvc]]
diff --git a/chapter_04_philosophy_and_refactoring.asciidoc b/chapter_04_philosophy_and_refactoring.asciidoc
@@ -32,7 +32,7 @@ Does all this stuff really have value? Is this a bit of a cargo cult?
 
 
 
-=== Programming Is Like Pulling a Bucket of Water Up [keep-together]#from a Well#
+=== Programming Is Like Pulling a Bucket of Water [.keep-together]#Up from a Well#
 
 ((("Test-Driven Development (TDD)", "philosophy of", "bucket of water analogy")))
 Ultimately, programming is hard.  Often, we are smart, so we succeed.
@@ -68,7 +68,7 @@ need to be a bit bloody-minded about it.
 .On the Merits of Trivial Tests for Trivial Functions
 **********************************************************************
 In the short term, it may feel a bit silly to write tests for simple
-functions and [keep-together]#constants#.
+functions and [.keep-together]#constants#.
 
 It's perfectly possible to imagine still doing ``mostly'' TDD,
 but following more relaxed rules where you don't unit test _absolutely_ everything.
@@ -299,7 +299,7 @@ $ *git commit -am "Functional test now checks we can input a to-do item"*
 
 
 
-=== The "Don't Test Constants" Rule, and Templates to the Rescue
+=== The "Don't Test Constants" Rule, and Templates [.keep-together]#to the Rescue#
 
 
 ((("“Don’t Test Constants” rule", primary-sortas="Don’t Test Constants rule")))
diff --git a/chapter_05_post_and_database.asciidoc b/chapter_05_post_and_database.asciidoc
@@ -797,7 +797,7 @@ Now we get to the `self.fail('Finish the test!')`.
 If we get rid of that and finish writing our FT,
 to add the check for adding a second item to the table
 (copy and paste is our friend),
-we begin to see that our first cut solution really isn't going to, um, cut it:
+we begin to see that our first cut solution really isn't going to, um, [.keep-together]#cut it#:
 
 [role="sourcecode"]
 .functional_tests.py (ch05l017)
@@ -965,10 +965,10 @@ and databases are a stalwart solution in this area.
 [[django_ORM_first_model]]
 === The Django ORM and Our First Model
 
-((("Object-Relational Mapper (ORM)", id="orm05")))
-((("Django framework", "Object-Relational Mapper (ORM)", id="DJForm05")))
-((("database testing", "Object-Relational Mapper (ORM)", id="DBTorm05")))
-An Object-Relational Mapper (ORM) is a layer of abstraction for data stored in a database
+((("object-relational mapper (ORM)", id="orm05")))
+((("Django framework", "object-relational mapper (ORM)", id="DJForm05")))
+((("database testing", "object-relational mapper (ORM)", id="DBTorm05")))
+An object-relational mapper (ORM) is a layer of abstraction for data stored in a database
 with tables, rows, and columns.
 It lets us work with databases using familiar object-oriented metaphors that work well with code.
 Classes map to database tables, attributes map to columns,
@@ -1384,7 +1384,7 @@ If you wanted to write our tests in a way that stays at the HTTP level—that tr
 by sending more than one:
 
 [role="sourcecode skipme"]
-.lists/tests/test_views.py
+.lists/tests/tests.py
 ====
 [source,python]
 ----
@@ -1731,7 +1731,7 @@ def home_page(request):
 ====
 
 [role="pagebreak-before less_space"]
-=== Better Unit Testing Practice: Each Test Should Test One Thing
+=== Better Unit Testing Practice: Each Test Should Test [.keep-together]#One Thing#
 
 ((("unit tests", "testing only one thing")))
 ((("testing best practices")))((("POST requests", "POST test is too long code smell, addressing")))
@@ -2146,7 +2146,7 @@ Where are we?  How is progress on our app, and what have we learned?
 But we've got a couple of items on our own to-do list,
 namely getting the FT to clean up after itself,
 and perhaps more critically,
-adding support for more than one list.
+adding support for more than one list:
 
 [role="scratchpad"]
 *****
diff --git a/chapter_06_explicit_waits_1.asciidoc b/chapter_06_explicit_waits_1.asciidoc
@@ -6,7 +6,7 @@ let's take care of a couple of housekeeping items.
 At the end of the last chapter, we made a note
 that different test runs were interfering with each other, so we'll fix that.
 I'm also not happy with all these ++time.sleep++s peppered through the code;
-they seem a bit unscientific, so we'll replace them with something more reliable.
+they seem a bit unscientific, so we'll replace them with something more reliable:
 
 [role="scratchpad"]
 *****
@@ -55,7 +55,7 @@ _manage.py_, which will run tests from any files whose name begins with _test__.
 To keep things neat and tidy, let's make a folder for our FTs,
 so that it looks a bit like an app.
 All Django needs is for it to be a valid Python package directory
-(i.e., one with a +++<i>___init___.py</i>+++ in it):
+(i.e., one with a +++<i>___init___.py</i>+++ [.keep-together]#in it#):
 
 [subs=""]
 ----
diff --git a/chapter_07_working_incrementally.asciidoc b/chapter_07_working_incrementally.asciidoc
@@ -471,7 +471,7 @@ TIP: Watch out for trailing slashes in URLs,
     They're a common source of confusion:
     Django will return a 301 redirect rather than a 404
     if you try to access a URL that's missing its trailing slash.footnote:[
-    The setting that controls this is called https://docs.djangoproject.com/en/5.2/ref/settings/#append-slash[APPEND_SLASH].
+    The setting that controls this is called https://docs.djangoproject.com/en/5.2/ref/settings/#append-slash[`APPEND_SLASH`].
     ]
     ((("troubleshooting", "URL mappings")))
 
@@ -684,7 +684,7 @@ OK
 ----
 
 
-==== The FTs detect a regression
+==== The FTs Detect a Regression
 
 As always when we get to passing unit tests,
 we run the FTs to check how things are doing
@@ -790,7 +790,7 @@ the way down to line 62 in the first FT,
 so we've at least added a first item.
 And our unit tests are all passing,
 so we're pretty sure the URLs and views that we _do_ have are doing what they should.
-Let's have a quick look at those unit tests to see what they tell us:
+Let's have a quick look at those unit tests to see what they [.keep-together]#tell us#:
 
 
 [subs="specialcharacters,quotes"]
@@ -980,7 +980,7 @@ It feels like the responsibilities of our two views are a little tangled up.
 Let's try and disentangle them.
 
 [role="pagebreak-before less_space"]
-=== Another Small Step: A Separate Template for Viewing Lists
+=== Another Small Step: A Separate Template [.keep-together]#for Viewing Lists#
 
 ((("multiple lists testing", "separate list viewing templates", id="MLTseparate07")))
 ((("templates", "separate list viewing templates", id="TMPseparate07")))
diff --git a/chapter_08_prettification.asciidoc b/chapter_08_prettification.asciidoc
@@ -741,7 +741,7 @@ AssertionError: 102.5 != 512 within 10 delta (409.5 difference)
 That's because, although `runserver` automagically finds static files,
 +Live&#x2060;S&#x2060;e&#x2060;r&#x2060;v&#x2060;e&#x2060;r&#x200b;T&#x2060;e&#x2060;s&#x2060;t&#x2060;Case+ doesn't.
 Never fear, though:
-the Django developers have made an even more magical test class
+the Django developers have made an even [.keep-together]#more magical# test class
 called `StaticLiveServerTestCase`
 (see https://oreil.ly/mh-iO[the docs]).
 
@@ -955,7 +955,8 @@ That's it! Definitely time for a commit:
 
 [subs="specialcharacters,quotes"]
 ----
-$ *git status* # changes tests.py, base.html, list.html, settings.py, + untracked lists/static
+$ *git status* # changes tests.py, base.html, list.html, settings.py,
+             # and untracked lists/static
 $ *git add .*
 $ *git status* # will now show all the bootstrap additions
 $ *git commit -m "Use Bootstrap to improve layout"*
@@ -1057,7 +1058,7 @@ class HomePageTest(TestCase):
 
 <2> Here's where we use a CSS selector to find our form,
     implicitly also checking that it has `method="POST"`.
-    The `cssselect()` method returns a list matching elements.
+    The `cssselect()` method returns a list of matching elements.
 
 <3> The `[form] =` is worth a mention.
     What we're using here is a special assignment syntax called "unpacking",
diff --git a/chapter_09_docker.asciidoc b/chapter_09_docker.asciidoc
@@ -455,7 +455,7 @@ What's happened there is that Docker has:
 Cool! We'll find out more about all of these steps as the chapter progresses.
 
 
-NOTE: On macOS, if you get errors saying `command not found: docker"`,
+NOTE: On macOS, if you get errors saying `command not found: docker`,
   obviously the first thing you should do is Google for "macOS command not found Docker",
   but at least one reader has reported that the solution was
   Docker Desktop > Settings > Advanced > Change from User to System.
diff --git a/chapter_10_production_readiness.asciidoc b/chapter_10_production_readiness.asciidoc
@@ -88,10 +88,7 @@ CMD ["gunicorn", "--bind", ":8888", "superlists.wsgi:application"]  # <2>
 
 <1> Installation is a standard `pip install`.
 
-<2> Gunicorn has its own command line, `gunicorn`.
-  It needs to know a path to a WSGI server,
-  which is usually a function called `application`.
-  Django provides one in _superlists/wsgi.py_.
+<2> Gunicorn has its own command line, `gunicorn`. Here's where we invoke it, including telling it which port to use, and supplying the dot-notation path to the WSGI server provided by Django.
 
 As in the previous chapter, we can use the `docker build && docker run`
 pattern to try out our changes by rebuilding and rerunning our container:
@@ -999,7 +996,7 @@ element: [id="id_list_table"]; [...]
 // explaining in the previous chapter when we do.
 
 And you might spot in the browser that we just see a minimal error page,
-with no debug info (try it manually if you like).
+with no debug info, as in <<minimal-error-page>> (try it manually if you like).
 
 [[minimal-error-page]]
 .Minimal default server error 500
@@ -1172,7 +1169,7 @@ but we've at least touched on many or most of the things you might need to think
 when considering production-readiness. We've worked in small steps and used our tests all the way along,
 and we're now ready to deploy our container to a real server!
 
-Find out how, in our next exciting instalment...
+Find out how, in our next exciting installment...
 
 TIP: One more recommendation for PythonSpeed and its
     https://pythonspeed.com/docker[Docker Packaging for Python Developers]
diff --git a/chapter_12_ansible.asciidoc b/chapter_12_ansible.asciidoc
@@ -56,24 +56,6 @@ It doesn't need much, it just feels unfinished to me.
 ////
 
 
-.Feedback Request
-*******************************************************************************
-Your feedback is enthusiastically solicited!((("feedback to author")))
-
-This chapter is entirely new for this edition of the book,
-so I'd love to hear about how people get on with it.
-Are the explanations clear?
-Did you manage to make the various listings and scripts work
-without a hitch?
-
-Reach out at obeythetestinggoat@gmail.com, or via
-https://github.com/hjwp/Book-TDD-Web-Dev-Python/issues[GitHub Issues]
-and Pull Requests.
-
-I hope you enjoy the new version!
-*******************************************************************************
-
-
 === A First Cut of an Ansible Playbook for Deployment
 
 Let's start using Ansible a little more seriously.((("Ansible", "automated deployments with", "first draft of playbook for deployment", id="ix_Ansautdplybk")))((("Docker", "Ansible running simple container on our server", id="ix_DckAns")))
@@ -1083,7 +1065,8 @@ Let's push that up with `ansible-playbook`:
 
 [subs="specialcharacters,macros"]
 ----
-$ pass:quotes[*ansible-playbook --user=elspeth -i staging.ottg.co.uk, infra/deploy-playbook.yaml -v*]
+$ pass:quotes[*ansible-playbook --user=elspeth -i staging.ottg.co.uk, \
+  infra/deploy-playbook.yaml -v*]
 [...]
 ----
 
diff --git a/chapter_13_organising_test_files.asciidoc b/chapter_13_organising_test_files.asciidoc
@@ -583,7 +583,7 @@ and multiple times:
 ...
 >>> addthree(2)
 5
->>> myfn = lambda: addthree(2)  # note addthree is not called immediately here
+>>> myfn = lambda: addthree(2)  # note addthree isn't called immediately here
 >>> myfn
 <function <lambda> at 0x7f3b140339d8>
 >>> myfn()
@@ -769,7 +769,7 @@ Usually, they are exactly the same as regular packages (which _do_ have a +++<i>
 but the Django test runner does not recognise them.]
 and thus discovered by the test runner.
 
-Now we turn _test_all.py_ into two files—one called _test_views.py_, which will only contains view tests,
+Now we turn _test_all.py_ into two files—one called _test_views.py_, which will only contain view tests,
 and one called _test_models.py_.
 I'll start by making two copies:
 
@@ -879,7 +879,7 @@ Don't refactor against failing tests::
     * This applies strongly to unit tests. With FTs, because we
       often develop against red FTs anyway, it's sometimes more tempting to
       refactor against failing tests. My suggestion is to avoid that temptation
-      and use an early return, so that it's 100% clear if, during a refactory,
+      and use an early return, so that it's 100% clear if, during a refactor,
       you accidentally introduce a regression that's picked up in your FTs.
     * You can occasionally put a skip on a test that is testing something you
       haven't written yet.
diff --git a/chapter_14_database_layer_validation.asciidoc b/chapter_14_database_layer_validation.asciidoc
@@ -356,14 +356,14 @@ and, if so, we do this:
 ----
   <form method="POST" action="{% block form_action %}{% endblock %}">
     <input
-      class="form-control form-control-lg {% if error %}is-invalid{% endif %}"  <1>
+      class="form-control form-control-lg {% if error %}is-invalid{% endif %}" <1>
       name="item_text"
       id="id_new_item"
       placeholder="Enter a to-do item"
     />
     {% csrf_token %}
     {% if error %}
-      <div class="invalid-feedback">{{ error }}</div>  <2>
+      <div class="invalid-feedback">{{ error }}</div> <2>
     {% endif %}
   </form>
 ----
diff --git a/chapter_16_advanced_forms.asciidoc b/chapter_16_advanced_forms.asciidoc
@@ -18,9 +18,9 @@ or if you're reading this book for the TDD rather than for the Django.
 
 If you're still learning Django, there's good stuff in here!
 If you want to just skim-read, that's OK too.
-Make sure you take a quick look at the
-<<testing-for-silliness,aside on developer silliness>>,
-and the <<what-to-test-in-views,recap on testing views>> at the end.
+Make sure you take a quick look at
+<<testing-for-silliness>>,
+and <<what-to-test-in-views>> at the end.
 
 
 [role="pagebreak-before less_space"]
diff --git a/chapter_17_javascript.asciidoc b/chapter_17_javascript.asciidoc
@@ -213,7 +213,7 @@ We'll come back and look at the spiking process again,
 with a weightier Python/Django example,
 in <<chapter_19_spiking_custom_auth>> .]
 
-Before we start, let's commit our FT.  When embarking on a slate,
+Before we start, let's commit our FT.  When embarking on a spike,
 you want to be able to get back to a clean slate:
 
 [role="small-code"]
@@ -890,7 +890,7 @@ image::images/tdd3_1706.png["Screenshot of devtools console showing the textInpu
 One of the difficulties with JavaScript in general, and testing in particular,
 is understanding the order of execution of our code (i.e., what happens when).
 When does our code in _lists.js_ run, and when do each of our tests run?
-And how does that interact with global state—that is, the DOM of our web page
+How do they all interact with global state—that is, the DOM of our web page
 and the fixtures that we've already seen are supposed to be cleaned up after each test?
 
 [role="pagebreak-before less_space"]
@@ -1447,7 +1447,7 @@ $ *git commit -m"Despike our js, add jasmine tests"*
 ----
 
 
-NOTE: We're using `<script>` tag to import our code,
+NOTE: We're using a `<script>` tag to import our code,
   but modern JavaScript lets you use `import` and `export` to explicitly
   import particular parts of your code.((("JavaScript", "import and export in to import code")))
   However, that involves specifying the scripts as modules,
diff --git a/chapter_18_second_deploy.asciidoc b/chapter_18_second_deploy.asciidoc
@@ -27,7 +27,7 @@ Let's make a little checklist of pre-deployment tasks:
 TIP: A deployment checklist like this should be a temporary measure.
   Once you've worked through it manually a few times,
   you should be looking to take the next step in automation:
-  continuous deployment straight using a CI/CD (continuous integration/continuous development) pipeline. We'll touch on this in <<chapter_25_CI>>.
+  continuous deployment straight to production using a CI/CD (continuous integration/continuous development) pipeline. We'll touch on this in <<chapter_25_CI>>.
 
 
 === A Full Test Run Locally
@@ -210,7 +210,7 @@ At this point, you have two choices:
 
 1. Delete the database on the server and try again—after all, it's only a toy project!
 
-2. Create about data migrations. You can find out more in the https://docs.djangoproject.com/en/5.2/topics/migrations/#data-migrations[Django migrations docs].
+2. Create a data migration. You can find out more in the https://docs.djangoproject.com/en/5.2/topics/migrations/#data-migrations[Django migrations docs].
 
 
 ==== How to Delete the Database on the Staging Server
diff --git a/chapter_19_spiking_custom_auth.asciidoc b/chapter_19_spiking_custom_auth.asciidoc
@@ -749,7 +749,7 @@ Time to de-spike!
 === De-spiking
 
 ((("spiking and de-spiking", "spiking magic links authentication", startref="ix_spkauth")))((("spiking and de-spiking", "de-spiking authentication code", id="SDde18")))((("authentication", "de-spiking authentication code", id="ix_authdes")))
-De-spiking means rewriting your prototype code using TDD. De-spiking means rewriting your prototype code using TDD.  In this section, we’ll work through how to do that in a safe and methodical way. We’ll take the knowledge we’ve acquired during the spiking process—whether that’s in our heads, in our notes, or in our branch in Git—and apply it as we re-implement gradually in a test-first way. And the hope is that our code will turn out a bit nicer the second time around!
+De-spiking means rewriting your prototype code using TDD. In this section, we’ll work through how to do that in a safe and methodical way. We’ll take the knowledge we’ve acquired during the spiking process—whether that’s in our heads, in our notes, or in our branch in Git—and apply it as we re-implement gradually in a test-first way. And the hope is that our code will turn out a bit nicer the second time around!
 
 ==== Making a Plan
 
diff --git a/chapter_20_mocking_1.asciidoc b/chapter_20_mocking_1.asciidoc
diff --git a/chapter_23_debugging_prod.asciidoc b/chapter_23_debugging_prod.asciidoc
diff --git a/chapter_25_CI.asciidoc b/chapter_25_CI.asciidoc
diff --git a/chapter_26_page_pattern.asciidoc b/chapter_26_page_pattern.asciidoc
diff --git a/chapter_27_hot_lava.asciidoc b/chapter_27_hot_lava.asciidoc
diff --git a/part4.asciidoc b/part4.asciidoc
diff --git a/pre-requisite-installations.asciidoc b/pre-requisite-installations.asciidoc
diff --git a/theme/pdf/pdf.css b/theme/pdf/pdf.css
