Merge branch 'main' into preface-review

Author: hjwp

.github/workflows/tests.yml

@@ -64,10 +64,10 @@ jobs:
           git config --global user.name "Elspeth See-Eye"
           git config --global init.defaultBranch main
 
-      - name: Set up Python 3.13
-        uses: actions/setup-python@v5
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.13'
+          python-version: '3.14'
 
       - name: Install apt stuff and other dependencies
         shell: bash

.python-version

@@ -1 +1 @@
-3.13
+3.14

Makefile

@@ -83,6 +83,7 @@ xmllint_%: %.asciidoc
 		-e 's/’/\’/g' \
 		-e 's/…/\…/g' \
 		-e 's/ /\ /g' \
+		-e 's/×/\×/g' \
 		| xmllint --noent --noout -
 
 

acknowledgments.asciidoc

@@ -4,7 +4,7 @@
 Lots of people to thank, without whom this book would never have happened,
 and/or would have been even worse than it is.
 
-Thanks first to "Greg" at $OTHER_PUBLISHER, who was the first person to
+Thanks first to "Greg" at `$OTHER_PUBLISHER`, who was the first person to
 encourage me to believe it really could be done. Even though your employers
 turned out to have overly regressive views on copyright, I'm forever grateful
 that you believed in me.
@@ -17,12 +17,12 @@ now changed the standard employment contract to say "no books").  Thanks also
 for your ongoing wisdom and for setting me off on the testing path.
 
 Thanks to my other colleagues, Glenn Jones and Hansel Dunlop, for being
-invaluable sounding boards, and for your patience with my one-track record
+invaluable sounding boards, and for your patience with my one-track-record
 conversation over the last year.
 
-Thanks to my wife Clementine, and to both my families, without whose support
+Thanks to my wife, Clementine, and to both my families—without whose support
 and patience I would never have made it.  I apologise for all the time spent
-with nose in computer on what should have been memorable family occasions. I
+with my nose in the computer on what should have been memorable family occasions. I
 had no idea when I set out what the book would do to my life ("Write it in my
 spare time, you say?  That sounds reasonable...").  I couldn't have done it
 without you.
@@ -32,18 +32,18 @@ Bache, for your encouragements and invaluable feedback.   Especially Emily,
 who actually conscientiously read every single chapter.  Partial credit
 to Nick and Jon, but that should still be read as eternal gratitude. Having
 y'all around made the whole thing less of a lonely endeavour. Without all of
-you the book would have been little more than the nonsensical ramblings of an
+you, the book would have been little more than the nonsensical ramblings of an
 idiot.
 
-Thanks to everyone else who's given up some of their time to give some
+Thanks to everyone else who's given up their time to give some
 feedback on the book, out of nothing more than the goodness of their heart:
 Gary Bernhardt, Mark Lavin, Matt O'Donnell, Michael Foord, Hynek Schlawack,
 Russell Keith-Magee, Andrew Godwin, Kenneth Reitz, and Nathan Stocks.  Thanks
 for being much smarter than I am, and for preventing me from saying several
 stupid things.  Naturally, there are still plenty of stupid things left in the
 book, for which y'all can absolutely not be held responsible.
 
-Thanks to my editor Meghan Blanchette, for being a very friendly and likeable
+Thanks to my editor, Meghan Blanchette, for being a very friendly and likeable
 slave driver, and for keeping the book on track, both in terms of timescales
 and by restraining my sillier ideas.  Thanks to all the others at
 O'Reilly for your help, including Sarah Schneider, Kara Ebrahim, and
@@ -53,7 +53,7 @@ on the merits of Chicago School quotation/punctuation rules, but I sure am
 glad you were around.  And thanks to the design department for giving us a goat
 for the cover!
 
-And thanks most especially to all my Early Release readers, for all your help
+And thanks most especially to all my early release readers, for all your help
 picking out typos, for your feedback and suggestions, for all the ways in
 which you helped to smooth out the learning curve in the book, and most of
 all for your kind words of encouragement and support that kept me going.
@@ -79,6 +79,7 @@ and make it up to you in any way I can.
 And finally thanks to you, the latest reader, for deciding to check out
 the book!  I hope you enjoy it.
 
+[role="pagebreak-before less_space"]
 === Additional Thanks for the Second Edition
 
 Thanks to my wonderful editor for the second edition, Nan Barber, and to
@@ -101,15 +102,15 @@ and many, many more.
 
 === Additional Thanks for the Third Edition
 
-Thanks to my editor Rita Fernando,
+Thanks to my editor, Rita Fernando,
 thanks to my tech reviewers
 Béres Csanád,
 David Seddon,
 Sebastian Buczyński,
 and Jan Giacomelli,
-and thanks to all the Early Release readers for your feedback,
+and thanks to all the early release readers for your feedback,
 big and small, including
-Jonathan H,
+Jonathan H.,
 James Evans,
 Patrick Cantwell,
 Devin Schumacher,
@@ -130,8 +131,9 @@ Lars Berberich,
 Rodrigo Jacznik,
 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.
 
 

ai_preface.asciidoc

@@ -1,6 +1,6 @@
 [[ai_preface]]
 [preface]
-== Preface to the Third Edition: TDD in the Age of AI
+== Preface to the Third Edition: [.keep-together]#TDD in the Age of AI#
 
 Is there any point in learning TDD now that AI can write code for you?
 A single prompt could probably generate the entire example application in this book,
@@ -10,13 +10,13 @@ The truth is that it's too early to tell.  AI is still in its infancy,
 and who knows what it'll be able to do in a few years or even months' time.
 
 
-=== AI is Both Insanely Impressive and Incredibly Unreliable
+=== AI Is Both Insanely Impressive and Incredibly Unreliable
 
 What we do know is that right now,
 AI is both insanely impressive and incredibly unreliable.
 
-Beyond being able to understand and respond to prompts in normal human language --
-it's easy to forget how absolutely extraordinary that is; literally science-fiction
+Beyond being able to understand and respond to prompts in normal human language--it's
+easy to forget how absolutely extraordinary that is; literally science-fiction
 a few years ago--AI tools can generate working code, they can generate tests,
 they can help us to break down requirements, brainstorm solutions,
 quickly prototype new technologies.  It's genuinely astonishing.
@@ -32,7 +32,7 @@ code that's filled with copy-paste and duplication, weird hacks,
 and undecipherable spaghetti code that spells a maintenance nightmare.
 
 
-=== Mitigations for AI's Shortcomings Sure Look A Lot Like TDD
+=== Mitigations for AI's Shortcomings Sure Look a Lot Like TDD
 
 If you read the advice, even from AI companies themselves,
 about the best way to work with AI, you'll find that it
@@ -49,15 +49,15 @@ When we're thinking about code quality, the idea of having a human in the loop,
 with frequent pauses for review and refactoring,
 again seems like a key mitigation.
 
-In short, all of the techniques of Test-Driven Development that are outlined in this book:
+In short, all of the techniques of test-driven development that are outlined in this book:
 
 * Defining a test that describes each small change of functionality,
   before we write the code for it
 
 * Breaking our problem down into small pieces and working incrementally,
   with frequent test runs to catch bugs, regressions, and hallucinations
 
-* The "refactor" step in TDD's Red/Green/Refactor cycle,
+* The "refactor" step in TDD's red/green/refactor cycle,
   which gives us a regular reminder for the human in the loop to review and improve the code.
 
 
@@ -69,7 +69,7 @@ when working with AI.
 
 === Leaky Abstractions and the Importance of Experience
 
-https://www.joelonsoftware.com/2002/11/11/the-law-of-leaky-abstractions/["Leaky abstractions"]
+https://oreil.ly/PgWjL["Leaky abstractions"]
 are a diagnosis of a common problem in software development,
 whereby higher-level abstractions fail in subtle ways,
 and the complexities of the underlying system leak through.
@@ -84,7 +84,7 @@ In a similar way, AI offers us a new, higher-level abstraction around writing co
 but we can already see the "leaks" in the form of hallucinations and poor code quality.
 And by analogy to the 3GLs, the programmers who are going to be most effective with AI
 are going to be the ones who "know what good looks like",
-both in terms of code quality, test structure and so on,
+both in terms of code quality, test structure, and so on,
 but also in terms of what a safe and reliable workflow for software development looks like.
 
 
@@ -97,6 +97,10 @@ Its ability to write that _first_ test,
 the one where, as we'll see, a lot of the design (and thinking) happens in TDD,
 was much more mixed.
 
+// SEBASTIAN: Idea for a frame with actionable advice: "Make sure there are at least few examples of tests before you'll make AI assistant write more. Show it what 'good' looks like."
+
+// SEBASTIAN: Another idea for a frame with actionable advice: "Simple things like writing a meaningful test name or describing in comment what you want to test can help immensely AI working in autocomplete mode."
+
 Similarly when working in a less "autocomplete" and more "agentic" mode,
 I saw AI tools do very well on simple problems with clear instructions,
 but when trying to deal with more complex logic and requirements with ambiguity,

appendix_CD.asciidoc

@@ -4,14 +4,14 @@
 
 .Warning
 *******************************************************************************
-🚧 Warning, this appendix is just a placeholder / rough sketch.
+This appendix is just a placeholder / rough sketch.
 
 It should have the outline of what you need to set up automated deploys tho!
 Why not give it a try?
 
 *******************************************************************************
 
-((("Continuous Delivery (CD)")))
+((("continuous delivery (CD)")))
 This is the next step after CI.
 Once we have a server that automatically does things every time we push,
 we can take the next step in automating our deploys,

appendix_Django_Class-Based_Views.asciidoc

@@ -71,7 +71,7 @@ def home_page(request):
 ====
 
 
-https://docs.djangoproject.com/en/1.11/ref/class-based-views/[Looking through
+https://docs.djangoproject.com/en/5.2/ref/class-based-views/[Looking through
 the options], Django has a generic view called `FormView`—let's see how
 that goes:
 

appendix_IV_testing_migrations.asciidoc

@@ -120,7 +120,7 @@ sqlite3.IntegrityError: columns list_id, text are not unique
 Inserting a Data Migration
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-https://docs.djangoproject.com/en/1.11/topics/migrations/#data-migrations[Data
+https://docs.djangoproject.com/en/5.2/topics/migrations/#data-migrations[Data
 migrations] are a special type of migration that modifies data in the database
 rather than changing the schema.  We need to create one that will run before
 we apply the integrity constraint, to preventively remove any duplicates.
@@ -135,7 +135,7 @@ Migrations for 'lists':
 $ pass:[<strong>mv lists/migrations/0005_*.py lists/migrations/0005_remove_duplicates.py</strong>]
 ----
 
-Check out https://docs.djangoproject.com/en/1.11/topics/migrations/#data-migrations[the
+Check out https://docs.djangoproject.com/en/5.2/topics/migrations/#data-migrations[the
 Django docs on data migrations] for more info, but here's how we add some
 instructions to change existing data:
 

appendix_IX_cheat_sheet.asciidoc

@@ -11,9 +11,8 @@ I hope you find it useful!
 
 === Initial Project Setup
 
-((("cheat sheet", "project setup")))
-((("Django framework", "set up", "project creation")))
-* Start with a _User Story_ and map it to a first _functional test_.
+
+* Start with a _user story_ and map it to a first _functional test_.((("cheat sheet", "project setup")))((("Django framework", "set up", "project creation")))
 
 * Pick a test framework—`unittest` is fine, and options like `py.test`,
   `nose`, or `Green` can also offer some advantages.
@@ -33,30 +32,22 @@ Relevant chapters:
 <<chapter_02_unittest>>,
 <<chapter_03_unit_test_first_view>>.
 
-
+[role="pagebreak-before less_space"]
 === The Basic TDD Workflow: Red/Green/Refactor
 
-((("cheat sheet", "TDD workflow")))
-((("Test-Driven Development (TDD)", "overall process of")))
-
-* Red, Green, Refactor
-
+[role="two-col"]
+* Red, Green, Refactor((("cheat sheet", "TDD workflow")))((("Test-Driven Development (TDD)", "overall process of")))
 * Double-loop TDD (<<Double-Loop-TDD-diagram2>>)
-
 * Triangulation
-
 * The scratchpad
-
 * "3 Strikes and Refactor"
-
 * "Working State to Working State"
-
 * "YAGNI"
 
 
 [[Double-Loop-TDD-diagram2]]
 .Double-loop TDD
-image::images/double-loop-tdd-simpler.png["An inner red/green/refactor loop surrounded by an outer red/green of FTs"]
+image::images/tdd3_0405.png["An inner red/green/refactor loop surrounded by an outer red/green of FTs"]
 
 
 Relevant chapters:
@@ -68,15 +59,13 @@ Relevant chapters:
 
 === Moving Beyond Dev-Only Testing
 
-((("cheat sheet", "moving beyond dev-only testing")))
-
 * Start system testing early.
-  Ensure your components work together: web server, static content, database.
+  Ensure your components work together: web server, static content, database.((("cheat sheet", "moving beyond dev-only testing")))
 
 * Build a production environment early, and automate deployment to it.
-    - PaaS vs. VPS
+    - PaaS versus VPS
     - Docker
-    - Ansible vs Terraform
+    - Ansible versus Terraform
 
 * Think through deployment pain points: the database, static files,
   dependencies, how to customise settings, and so on.
@@ -88,13 +77,10 @@ Relevant chapters:
 <<part2>>,
 <<chapter_25_CI>>.
 
-
+[role="pagebreak-before less_space"]
 === General Testing Best Practices
 
-((("cheat sheet", "testing best practices")))
-((("testing best practices")))
-
-* Each test should test one thing.
+* Each test should test one thing.((("cheat sheet", "testing best practices")))((("testing best practices")))
 
 * Test behaviour rather than implementation.
 
@@ -118,7 +104,7 @@ Relevant chapters:
 * Use explicit rather than implicit waits, and the interaction/wait pattern.
 
 * Avoid duplication of test code--helper methods in a base class and the
-  Page pattern are possible solutions.
+  page pattern are possible solutions.
 
 * Avoid double-testing functionality.
   If you have a test that covers a time-consuming process (e.g., login),
@@ -149,6 +135,6 @@ Be aware that integration tests will get slower and slower over time.
 Find ways to shift the bulk of your testing to unit tests
 as your project grows in size and complexity.
 
-Relevant chapters:
+Relevant chapter:
 <<chapter_27_hot_lava>>.
 

appendix_X_what_to_do_next.asciidoc

@@ -36,7 +36,7 @@ and compare how much faster they are than running against Postgres.
 Set it up so that your local machine uses SQLite for testing,
 but your CI server uses Postgres.
 
-Does any of your functionality actually depend on postgres-specific features?
+Does any of your functionality actually depend on Postgres-specific features?
 What should you do then?
 
 
@@ -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),