Merge remote-tracking branch 'atlas/main'

Author: hjwp

ai_preface.asciidoc

@@ -35,7 +35,7 @@ and undecipherable spaghetti code that spells a maintenance nightmare.
 === 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 date that it
+about the best way to work with AI, you'll find that it
 performs best when working in small, well-defined contexts,
 with frequent checks for correctness.
 When taking on larger tasks, the advice is to break them down into smaller,

appendix_IX_cheat_sheet.asciidoc

@@ -56,7 +56,7 @@ Relevant chapters:
 
 [[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:

atlas.json

@@ -43,9 +43,10 @@
     "chapter_26_page_pattern.asciidoc",
     "chapter_27_hot_lava.asciidoc",
     "epilogue.asciidoc",
+    "bibliography.asciidoc",
     "appendix_IX_cheat_sheet.asciidoc",
     "appendix_X_what_to_do_next.asciidoc",
-    "appendix_github_links.asciidoc", 
+    "appendix_github_links.asciidoc",
     "ix.html",
     "author_bio.html",
     "colo.html"
@@ -92,4 +93,4 @@
   "lang": "en",
   "accent_color": "",
   "preprocessing": "none"
-}
+}

bibliography.asciidoc

@@ -6,9 +6,13 @@
 A few books about TDD and software development that I've mentioned in the book,
 and which I enthusiastically recommend.
 
-* Kent Beck, _Test Driven Development: By Example_, Addison-Wesley
-* Martin Fowler, _Refactoring_, Addison-Wesley
-* Ross Anderson, _Security Engineering, Third Edition_, Addison-Wesley: https://www.cl.cam.ac.uk/archive/rja14/book.html
-* Steve Freeman and Nat Pryce, _Growing Object-Oriented Software Guided by Tests_, Addison-Wesley
-* Hal Abelson, Jerry Sussman and Julie Sussman, _Structure and Interpretation of Computer Programs_ (SICP), MIT Press
-* Dave Farley, _Modern Software Engineering_,  Addison-Wesley
+++++
+<ul class="simplelist">
+<li>Kent Beck, <em>Test Driven Development: By Example</em>, Addison-Wesley</li>
+<li>Martin Fowler, <em>Refactoring_, Addison-Wesley</em></li>
+<li>Ross Anderson, <em>Security Engineering, Third Edition</em>, Addison-Wesley: https://www.cl.cam.ac.uk/archive/rja14/book.html</li>
+<li id="GOOSGBT">Steve Freeman and Nat Pryce, <em>Growing Object-Oriented Software Guided by Tests</em>, Addison-Wesley</li>
+<li>Hal Abelson, Jerry Sussman and Julie Sussman, <em>Structure and Interpretation of Computer Programs</em> (SICP), MIT Press</li>
+<li>Dave Farley, <em>Modern Software Engineering</em>,  Addison-Wesley</li>
+</ul>
+++++

chapter_01.asciidoc

@@ -51,7 +51,7 @@ That's why they seldom fall off things, see, no matter how steep they are.
 As you can see in <<tree_goat>>.
 [[tree_goat]]
 .Goats are more agile than you think (source: http://www.flickr.com/photos/caitlinstewart/2846642630/[Caitlin Stewart, on Flickr])
-image::images/twp2_0101.png["A picture of a goat up a tree", scale="50"]
+image::images/tdd3_0101.png["A picture of a goat up a tree", scale="50"]
 
 
 We'll proceed with nice small steps;
@@ -150,7 +150,7 @@ you might encounter a strange popup window, such as the one shown in <<firefox_u
 
 [[firefox_upgrade_popup]]
 .Firefox Wants to Install a New What Now?
-image::images/firefox_upgrade_popup.png["A popup window saying 'Firefox is trying to install a new helper tool.' and prompting for a username and password"]
+image::images/tdd3_0102.png["A popup window saying 'Firefox is trying to install a new helper tool.' and prompting for a username and password"]
 
 This happens when Firefox has automatically downloaded a new version,
 in the background.
@@ -277,7 +277,7 @@ back in the original shell, using Ctrl-C.
 
 [[installed_successfully_screenshot]]
 .It worked!
-image::images/twp2_0102.png["Screenshot of Django Installed Successfully Screen"]
+image::images/tdd3_0103.png["Screenshot of Django Installed Successfully Screen"]
 
 
 .Adieu to Roman Numerals!
@@ -505,7 +505,7 @@ PS - to quit vim, it's Esc, then `:q!`]
 
 [[first_git_commit]]
 .First Git commit
-image::images/twp2_0103.png["Screenshot of git commit vi window"]
+image::images/tdd3_0104.png["Screenshot of git commit vi window"]
 
 
 NOTE: If you want to really go to town on Git,

chapter_04_philosophy_and_refactoring.asciidoc

@@ -59,7 +59,7 @@ That way you don't have to be smart _all_ the time.
 
 [[figure4-1]]
 .Test ALL the things (original illustration source: http://bit.ly/1iXxdYp[Allie Brosh, Hyperbole and a Half])
-image::images/twp2_0401.png["Test ALL the things",float="right"]
+image::images/tdd3_0401.png["Test ALL the things",float="right"]
 
 
 OK, perhaps _in general_, you're prepared to concede that TDD is a good
@@ -785,7 +785,7 @@ stick to small steps; keep refactoring and functionality changes entirely separa
 
 [[RefactoringCat]]
 .Refactoring Cat--be sure to look up the full animated GIF (source: 4GIFs.com)
-image::images/twp2_0402.png["An adventurous cat, trying to refactor its way out of a slippery bathtub"]
+image::images/tdd3_0402.png["An adventurous cat, trying to refactor its way out of a slippery bathtub"]
 
 
 NOTE: We'll come across "Refactoring Cat" again during this book,
@@ -990,14 +990,14 @@ See <<simple-tdd-diagram>>.
 
 [[simple-tdd-diagram]]
 .TDD process as a flowchart, including the unit test / code cycle
-image::images/tdd-process-unit-tests-only-excalidraw.png["A flowchart with boxes for tests, coding and refactoring, with yes/no labels showing when we move forwards or backwards"]
+image::images/tdd3_0403.png["A flowchart with boxes for tests, coding and refactoring, with yes/no labels showing when we move forwards or backwards"]
 
 It's very common to talk about this process using the three words
 _Red, Green, Refactor_. See <<red-green-refactor>>.
 
 [[red-green-refactor]]
 .Red, Green, Refactor
-image::images/red-green-refactor-excalidraw.png["Red, Green and Refactor as three nodes in a circle, with arrows flowing around."]
+image::images/tdd3_0404.png["Red, Green and Refactor as three nodes in a circle, with arrows flowing around."]
 
 * We write a test, and see it fail ("Red").
 * We cycle between code and tests until the test passes: "Green".
@@ -1013,7 +1013,7 @@ with an inner red/green/refactor loop being required to get an FT from Red to Gr
 
 [[double-loop-tdd-diagram]]
 .Double-Loop TDD: Inner and Outer Loops
-image::images/double-loop-tdd-simpler.png["An inner red/green/refactor loop surrounded by an outer red/green of FTs"]
+image::images/tdd3_0702.png["An inner red/green/refactor loop surrounded by an outer red/green of FTs"]
 
 When a new feature or business requirement comes along,
 we write a new (failing) FT to capture a high level view of the requirement.

chapter_05_post_and_database.asciidoc

@@ -332,7 +332,7 @@ you should see a page that looks like
 
 [[csrf_error_screenshot]]
 .Django DEBUG page showing CSRF error
-image::images/twp2_0501.png["Django DEBUG page showing CSRF error"]
+image::images/tdd3_0501.png["Django DEBUG page showing CSRF error"]
 
 
 .Security: Surprisingly Fun!
@@ -537,7 +537,7 @@ you'll see something like <<table_gone_screenshot>>.
 
 [[table_gone_screenshot]]
 .I see my item text but no table...
-image::images/todo_list_table_disappeared.png["A screenshot of the page after submission, which just has the raw text You submitted: Buy asparagus"]
+image::images/tdd3_0502.png["A screenshot of the page after submission, which just has the raw text You submitted: Buy asparagus"]
 
 What we really want to do is add the POST submission
 to the todo items table in the home page template.
@@ -1366,6 +1366,7 @@ or it may be an indication that the thing you're testing is too complicated.
 Let's add that to a little to-do list of our own,
 perhaps on a piece of scrap paper:
 
+
 [role="scratchpad"]
 *****
 * 'Code smell: POST test is too long?'
@@ -1516,6 +1517,7 @@ I've added a couple of the other things that are on our mind:
 * 'Support more than one list!'
 *****
 
+
 Let's start with the first scratch pad item:
 _Don't save blank items for every request_.
 We could tack on an assertion to an existing test,
@@ -1702,6 +1704,7 @@ def home_page(request):
     It's actually closely related to "Display multiple items",
     so we'll put it just before that one:
 
+
 [role="scratchpad"]
 *****
 * '[strikethrough line-through]#Don't save blank items for every request#'
@@ -1711,6 +1714,7 @@ def home_page(request):
 * 'Support more than one list!'
 *****
 
+
 And here's the refactored version of _views.py_ using the `.objects.create()`
 helper method that Django provides, for one-line creation of objects:
 
@@ -1793,6 +1797,7 @@ Much better!  Back to our to-do list:
 * 'Support more than one list!'
 *****
 
+
 Crossing things off the list is almost as satisfying as seeing tests pass!
 
 The third and fourth items are the last of the "easy" ones.
@@ -1946,7 +1951,7 @@ as in <<operationalerror>>.
 [[operationalerror]]
 [role="width-75"]
 .Another helpful debug message
-image::images/django_operationalerror.png["Screenshot of Django debug page, saying OperationalError at / no such table: lists_item"]
+image::images/tdd3_0503.png["Screenshot of Django debug page, saying OperationalError at / no such table: lists_item"]
 
 
 [role="pagebreak-before less_space"]
@@ -2074,7 +2079,7 @@ But, as it's running, you may notice something is amiss, like in
 
 [[items_left_over_from_previous_run]]
 .There are list items left over from the last run of the test
-image::images/twp2_0503.png["There are list items left over from the last run of the test"]
+image::images/tdd3_0504.png["There are list items left over from the last run of the test"]
 
 
 Oh dear. It looks like previous runs of the test are leaving stuff lying around
@@ -2157,6 +2162,7 @@ adding support for more than one list.
 * 'Support more than one list!'
 *****
 
+
 I mean, we _could_ ship the site as it is, but people might find it strange
 that the entire human population has to share a single to-do list.
 I suppose it might get people to stop and think about

chapter_06_explicit_waits_1.asciidoc

@@ -23,6 +23,7 @@ they seem a bit unscientific, so we'll replace them with something more reliable
 * _Remove time.sleeps_
 *****
 
+
 Both of these changes will be moving us towards testing "best practices",
 making our tests more deterministic and more reliable.
 

chapter_07_working_incrementally.asciidoc

@@ -73,7 +73,7 @@ Something like <<multiple-lists-users-and-urls>>:
 
 [[multiple-lists-users-and-urls]]
 .Multiple users with multiple lists at multiple URLs
-image::images/multiple-lists-users-and-urls.png["An illustration showing two users looking at two different lists with different items, at different URLs."]
+image::images/tdd3_0701.png["An illustration showing two users looking at two different lists with different items, at different URLs."]
 
 
 ==== YAGNI!
@@ -162,6 +162,7 @@ Apart from anything else, you can't use PUT in a standard HTML form.)
 ((("", startref="MLTsmall07")))
 In summary, our scratchpad for this chapter looks something like this:
 
+
 [role="scratchpad"]
 *****
 * _Adjust model so that items are associated with different lists_
@@ -171,7 +172,6 @@ In summary, our scratchpad for this chapter looks something like this:
 *****
 
 
-
 === Implementing the New Design Incrementally Using TDD
 
 ((("Test-Driven Development (TDD)", "overall process of")))
@@ -198,7 +198,7 @@ we _don't_ touch to help make sure we don't break anything in the process.
 
 [[double-loop-tdd-diagram-2]]
 .The TDD Process With Both Functional and Unit Tests
-image::images/double-loop-tdd-simpler.png["An inner red/green/refactor loop surrounded by an outer red/green of FTs"]
+image::images/tdd3_1708.png["An inner red/green/refactor loop surrounded by an outer red/green of FTs"]
 
 
 [role="pagebreak-before less_space"]
@@ -1279,6 +1279,7 @@ Where are we with our own to-do list?
 * 'Add URLs for adding a new item to an existing list via POST'
 *****
 
+
 We've _sort of_ made progress on the second item,
 even if there's still only one list in the world.
 The first item is a bit scary.
@@ -1562,7 +1563,7 @@ and click around to see what's going on.
 
 [[post-in-dev-tools]]
 .Dev Tools Shows a POST Request to /
-image::images/devtools-post-request.png["screenshot of browser dev tools with a POST request in the network tab, with the File column showing /"]
+image::images/tdd3_0703.png["screenshot of browser dev tools with a POST request in the network tab, with the File column showing /"]
 
 
 Actually _both_ our forms are still pointing to the old URL.
@@ -1671,7 +1672,6 @@ And we can cross out an item on the to-do list:
 * 'Add URLs for adding a new item to an existing list via POST'
 *****
 
-
 === Biting the Bullet: Adjusting Our Models
 
 Enough housekeeping with our URLs.

chapter_08_prettification.asciidoc

@@ -59,7 +59,7 @@ It's a bit like testing a constant, in that tests usually wouldn't add any value
 
 [[homepage-looking-ugly]]
 .Our home page, looking a little ugly...
-image::images/ugly-homepage.png["Our home page, looking a little ugly."]
+image::images/tdd3_0801.png["Our home page, looking a little ugly."]
 
 
 ((("static files", "challenges of")))
@@ -736,7 +736,7 @@ as in <<list-page-centered>>.
 
 [[list-page-centered]]
 .Our site starts to look a little better...
-image::images/prettified-1.png["The list page with centered header."]
+image::images/tdd3_0802.png["The list page with centered header."]
 
 
 
@@ -842,7 +842,7 @@ That ends up looking something like <<jumbotron-header>>:
 
 [[jumbotron-header]]
 .A big grey box at the top of the page
-image::images/prettified-2.png["The homepage with a big grey box surrounding the title and input"]
+image::images/tdd3_0803.png["The homepage with a big grey box surrounding the title and input"]
 
 
 TIP: When hacking about with design and layout,
@@ -919,7 +919,7 @@ I think that looks great!
 
 [[dark-modeee]]
 .Dark Modeeeeeeeeee
-image::images/prettified-dark.png["Screenshot of lists page in dark mode. Cool."]
+image::images/tdd3_0804.png["Screenshot of lists page in dark mode. Cool."]
 
 
 But it's very much a matter of personal preference,
@@ -936,7 +936,7 @@ Getting it into shape took me a few goes, but I'm reasonably happy with it now
 
 [[homepage-looking-better]]
 .The lists page, looking... good enough for now.
-image::images/prettified-final.png["Screenshot of lists page in light mode with decent styling."]
+image::images/tdd3_0805.png["Screenshot of lists page in light mode with decent styling."]
 
 If you want to go further with customising Bootstrap,
 you need to get into compiling Sass.
@@ -982,6 +982,7 @@ Oh woops, we nearly forgot our scratchpad:
 * _Find a better way to unit test form+input elements_
 *****
 
+
 When working on layout and styling, you expect to spend most of your time
 in the browser, in a cycle of tweaking your HTML and hitting "refresh" to see
 the effects, with occasional runs of your layout FT, if you have one.