Merge pull request #40 from code4mathorg/StevenClontz/jmm2025-update

JMM 2025 updates

Author: StevenClontz

source/ch-coding.ptx

@@ -4,8 +4,9 @@
   <section xml:id="sec-codespaces">
     <title>Codespaces</title>
     <p>
-While the quick <c>GitHub.dev</c> interface is great
-for quick edits, many projects require the ability
+While the quick <c>GitHub.dev</c> interface we used
+to get started in <xref ref="ch-first-repo"/> is great
+for quick uploads or edits, many projects require the ability
 to run applications and execute code as you would on
 your personal computer. Fortunately, GitHub offers a
 service to run such programs on their servers.
@@ -240,50 +241,6 @@ Array.from({ length: 10 }, _ => {
       <caption>Sample Javascript code</caption>
     </listing>
   </section>
-  <section xml:id="sec-github-pages-codespace">
-    <title>Previewing GitHub Pages</title>
-    <p>
-Another useful application of Codespaces is the ability
-to preview your GitHub Pages site created in
-<xref ref="sec-using-a-template"/>. Return to that repository
-on <c>GitHub.com</c> and create a new Codespace
-(<xref ref="note-create-codespace"/>).
-    </p>
-    <p>
-To spin up your live preview, open a terminal by using the
-shortcut noted in <xref ref="remark-terminal-shortcut"/>. To make
-sure the necessary software has been installed, type <c>bundle</c>
-and hit <kbd>Enter</kbd>. Then, you can enter <c>jekyll serve</c>
-to start the preview server.
-    </p>
-    <p>
-You'll see some output, and eventually
-<c>Server address: http://127.0.0.1:4000</c>. At that time an
-alert will appear that says <q>Your application on port 4000
-is available</q>. You can use its <q>Open in browser</q> button,
-or hover over the <c>http://127.0.0.1:4000</c> link to be given
-the same option.
-    </p>
-    <p>
-This should open a URL such as
-<c>random-words-123randomletters789-4000.app.github.dev</c>,
-which will show a live preview of your GitHub Pages site in a new
-tab. As soon as you make edits in your Codespace tab, you can
-return to this tab to (within a second or two) see how your edits
-will update your live site. Note that this URL is private to you,
-and your public site won't be updated until you Commit &amp; Sync
-your changes
-(<xref ref="note-commit-sync"/>).
-    </p>
-    <p>
-Personally, I use <c>GitHub.dev</c> (or even just the
-<c>GitHub.com</c> edit button) rather than a full
-Codespace when adding a quick post or making a quick edit on
-many of my GitHub Pages websites. But the Codespace option is very
-handy for when bigger changes are necessary, and you want to make
-sure everything looks just right before pushing it live to the public.
-    </p>
-  </section>
   <section xml:id="sec-codespace-management">
     <title>Managing Your Codespaces</title>
     <p>
@@ -297,9 +254,9 @@ there is the option to pay for additional resources.
 As a mathematician
 who almost exclusively uses GitHub Codespaces for doing the kinds
 of work described in this handbook (and does so for much longer
-periods of time than a tpyical mathematician),
+periods of time than a typical mathematician),
 I've only surpassed GitHub's free quota on the rare occassion
-(and when I do, I've paid only \$2-\$6 per month).
+(and when I do, I've paid only <m>\$2</m>-<m>\$6</m> per month).
 I accomplish this by halting
 my Codespaces when I'm not actively working on them.
     </p>
@@ -343,9 +300,11 @@ Here is what these environments look like.
   <section xml:id="sec-powering-up-your-codespce">
     <title>Powering up your Codespce</title>
     <p>
-By default, your codespace will use a
-2-core processor, 8GB of RAM, and 32GB of storage, with a quota of
-40 usage hours per month. This is fine for many tasks,
+As of January 2025, a default codespace will use a
+2-core processor and 8GB of RAM, with a quota of
+60 usage hours and 15GB storage per month. (This is increased
+to 90 usage hours and 20GB storage for Pro/Education users.)
+This is fine for many tasks,
 but if you're doing data analysis (<xref ref="ch-jupyter"/>) or
 formalized mathematics (<xref ref="sec-lean"/>) you may want some
 more resources at your disposal.
@@ -374,5 +333,18 @@ the virtual machine that should be provisioned when creating a Codespace,
 allowing for the automatic installation of appropriate software/libraries/dependencies
 necessary for the use of a given repository.
     </p>
+    <remark>
+      <p>
+        Setting up a custom <c>.devcontainer</c> is a slick way to
+        ensure you and your collaborators/students are running exactly
+        the same software (including versions, dependencies, etc.)!
+        No more <q>It works on my machine</q> while <q>I can't get it
+        to work on my machine</q>!
+      </p>
+      <p>
+        See <url href="https://code.visualstudio.com/docs/devcontainers/create-dev-container#_create-a-devcontainerjson-file">VisualStudio.com/docs/devcontainers</url>
+        to learn more.
+      </p>
+    </remark>
   </section>
 </chapter>

source/ch-first-repo.ptx

@@ -227,4 +227,15 @@ on each commit to see exactly what has changed from the previous commit across
 all files.
         </p>
     </section>
+    <section>
+        <title>Next steps</title>
+        <p>
+Now that you've gotten the hang of the basics of
+committing and pushing changes to a repository,
+you can move on to using Codespaces to write
+and execute programs and code (<xref ref="ch-coding"/>)
+or setting up a webpage hosted by GitHub
+(<xref ref="ch-github-pages"/>).
+        </p>
+    </section>
 </chapter>

source/ch-website.ptx

@@ -19,7 +19,7 @@ without using HTML.)
         </p>
         <p>
 Use <c>GitHub.dev</c> (<xref ref="opening-github-dev"/>)
-to create three files in the root of your project.
+to create three files in the root of a new or existing repository.
             <ul>
                 <li>
                     <p>
@@ -243,8 +243,8 @@ edits. After a while (<xref ref="actions-progress" />) you should
 be able to refresh your website and see your updated title, name, etc.
 (In <xref ref="sec-github-pages-codespace"/>, we will learn how to
 preview our edits more quickly, and without needing to push them to a
-live website, but at the expense of a more complicated
-editing environment.) You can repeat this process after each of the
+live website, provided we're comfortable using a Codespace as explored in
+<xref ref="ch-coding"/>.) You can repeat this process after each of the
 edits described below to see your results reflected on the live website.
             </p>
         </subsection>
@@ -338,4 +338,48 @@ tags:
             </listing>
         </subsection>
     </section>
+  <section xml:id="sec-github-pages-codespace">
+    <title>Previewing GitHub Pages</title>
+    <p>
+Another useful application of Codespaces is the ability
+to preview your GitHub Pages site created in
+<xref ref="sec-using-a-template"/>. Return to that repository
+on <c>GitHub.com</c> and create a new Codespace
+(<xref ref="note-create-codespace"/>).
+    </p>
+    <p>
+To spin up your live preview, open a terminal by using the
+shortcut noted in <xref ref="remark-terminal-shortcut"/>. To make
+sure the necessary software has been installed, type <c>bundle</c>
+and hit <kbd>Enter</kbd>. Then, you can enter <c>jekyll serve</c>
+to start the preview server.
+    </p>
+    <p>
+You'll see some output, and eventually
+<c>Server address: http://127.0.0.1:4000</c>. At that time an
+alert will appear that says <q>Your application on port 4000
+is available</q>. You can use its <q>Open in browser</q> button,
+or hover over the <c>http://127.0.0.1:4000</c> link to be given
+the same option.
+    </p>
+    <p>
+This should open a URL such as
+<c>random-words-123randomletters789-4000.app.github.dev</c>,
+which will show a live preview of your GitHub Pages site in a new
+tab. As soon as you make edits in your Codespace tab, you can
+return to this tab to (within a second or two) see how your edits
+will update your live site. Note that this URL is private to you,
+and your public site won't be updated until you Commit &amp; Sync
+your changes
+(<xref ref="note-commit-sync"/>).
+    </p>
+    <p>
+Personally, I use <c>GitHub.dev</c> (or even just the
+<c>GitHub.com</c> edit button) rather than a full
+Codespace when adding a quick post or making a quick edit on
+many of my GitHub Pages websites. But the Codespace option is very
+handy for when bigger changes are necessary, and you want to make
+sure everything looks just right before pushing it live to the public.
+    </p>
+  </section>
 </chapter>

source/main.ptx

@@ -19,8 +19,8 @@
 
     <xi:include href="ch-git-github.ptx"/>
     <xi:include href="ch-first-repo.ptx"/>
-    <xi:include href="ch-website.ptx"/>
     <xi:include href="ch-coding.ptx"/>
+    <xi:include href="ch-website.ptx"/>
     <xi:include href="ch-collaboration.ptx"/>
     <xi:include href="ch-jupyter.ptx"/>
     <xi:include href="ch-projects.ptx"/>