Automate prereleases + update documentation of the build process (#104)

* Adds missing docs that should have been part of #102 (4ad7dca) * Add automated releases to CI again (fixes #106)
hpi-swa-lab · Apr 27, 2021 · 7bff3c5 · 7bff3c5
1 parent 964cb39
commit 7bff3c5
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 15 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -30,7 +30,7 @@ jobs:
         run: smalltalkci -s Squeak64-${{ matrix.smalltalk }} SBE-Tests.smalltalk.ston
         timeout-minutes: 15
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # for coverage reports
+          GITHUB_TOKEN: ${{ github.token }}  # for coverage reports
   tex-assertions:
     name: 🧪 @TEST assertions [${{ matrix.smalltalk }}]
     runs-on: ubuntu-latest
@@ -98,7 +98,7 @@ jobs:
         run: mv SBE.pdf SBE-${{ matrix.smalltalk }}.pdf
         env:
           SQUEAK_VERSION: ${{ matrix.smalltalk }}
-      - name: 💾 Store book
+      - name: 💾 Upload artifact
         uses: actions/upload-artifact@master
         with:
           name: book-${{ matrix.smalltalk }}
@@ -109,6 +109,33 @@ jobs:
           echo ::error::jobs.figures has failed, so the compiled PDF might miss some figures!
           echo "DEBUG_FIGURES=true" >> $GITHUB_ENV
           exit 1
+  release:
+    name: ✈ Create pre-release
+    needs: [tests, tex-assertions, build]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Load artifacts
+        uses: actions/download-artifact@master
+        with:
+          path: .
+      - uses: thedoctor0/zip-release@master
+        with:
+          filename: ListingSources.zip
+          path: listings
+      - uses: benjlevesque/[email protected]
+        id: short-sha
+      - name: 📣 Create pre-release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: untagged-${{ steps.short-sha.outputs.sha }}
+          body: ${{ github.event.head_commit.message }}
+          files: |
+            book-*/SBE-*.pdf
+            ListingSources.zip
+          prerelease: true
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
   notify:
     name: 📣 Notify community on failure
     needs: [tests, tex-assertions, build]

diff --git a/README.md b/README.md
@@ -1,12 +1,16 @@
-# Squeak by Example [![Build Status](https://travis-ci.com/hpi-swa-lab/SqueakByExample-english.svg?branch=master)](https://travis-ci.com/hpi-swa-lab/SqueakByExample-english)
+# Squeak by Example
+
+[![📕 Make Book](https://github.com/hpi-swa-lab/SqueakByExample-english/actions/workflows/build.yml/badge.svg)](https://github.com/hpi-swa-lab/SqueakByExample-english/actions/workflows/build.yml)
+[![Latest release](https://img.shields.io/github/v/release/hpi-swa-lab/SqueakByExample-english)](https://github.com/hpi-swa-lab/SqueakByExample-english/releases/latest)
+[![Latest preprint](https://img.shields.io/github/v/release/hpi-swa-lab/SqueakByExample-english?include_prereleases&label=preprint)](https://github.com/hpi-swa-lab/SqueakByExample-english/releases)
 
 This is the LaTeX source repository of the _Squeak by Example_ book.
 
 See the issues in the [Github repository](https://github.com/hpi-swa-lab/SqueakByExample-english) for the status of tasks for SBE.
 
 ---
 
-# File structure
+# Repository structure
 
 The main file is SBE.tex.  Chapters are in subdirectories.
 You can latex either the entire book, or each individual chapter.
@@ -30,26 +34,69 @@ to verify that you have added all the dependent files (e.g., figures).
 
 ## Build process
 
-The PDF of the book is built via Travis CI on each commit, which includes the execution of SBEtests and the generation of screenshots that are described by a figure script. Two PDFs are created, one for the latest Squeak release and one for the current Trunk version.
+The PDF of the book is built via GitHub Actions on each commit, which includes the execution of internal tests, the check of TEX-inlined `@TEST` assertions, and the generation of screenshots that are described by figure scripts.
+Two PDFs are created, one for the latest Squeak release and one for the current Trunk version.
+
+You can download the latest version of the book from the [Releases page](https://github.com/hpi-swa-lab/SqueakByExample-english/releases).
+
+The usual workflow to **add a scripted screenshot to the book** is as follows:
+
+1. Open the relevant `.tex` file and insert the following snipped before the `\figure` definition:
+
+   ```tex
+   \begin{ExecuteSmalltalkScript}
+   SBESqueakPicture writeTo: './figures/<name>.png' using: [:helper |
+   	self shouldBeImplemented
+   ]
+   \end{ExecuteSmalltalkScript}
+   
+   \begin{figure}
+      \centering
+      \includegraphics[scale=0.65]{<name>} 
+      \caption{<caption>.\label{fig:<name>}}
+   \end{figure}
+   ```
+
+2. Insert figure name, caption, and script generation logic in the template above.
+   Browse the repository to find existing examples.
+
+   **Tip:** You can also use `SBEDebuggingScreenshotRecorder` instead of `SBEFigureBuilder` for testing your screenshot script right in the image (the file won't be saved on disk in this case).
+
+3. Test your script by doing `SBEFigureBuilder buildAllTexFigures` (maybe you need to set `#resourceDirectory` before) or `SBEFigureBuilder buildFiguresWith: FSPath * 'your' / 'path'`.
+
+4. Build the PDF using the Makefile to make sure your screenshot looks well.
+
+5. Commit! 🚀 The PDF will automatically be built on the CI now ...
+
+6. If the build process has completed, you can watch the results [in the Actions tab of the GitHub repository](https://github.com/hpi-swa-lab/SqueakByExample-english/actions?query=branch%3Amaster) by opening the latest successful build and scrolling down to the artifacts.
+
+**To build the PDF manually,** do the following:
 
-The usual workflow to codify a screenshot is documented [here](https://github.com/hpi-swa-lab/SqueakByExample-english/issues/21#issue-516598115). If the build process completed, you can watch the results [here](https://drive.google.com/drive/folders/1tNIvN-9Vx8djNZYfSYuqhjheb-EgJuTc).
-To build the PDF manually, do the following:
 ### I. Installation
+
 1. Get a support Squeak image (any release since 5.3 or the latest Trunk image)
-2. Open the Git Browser and clone this repository
+
+2. Open the Git Browser and clone this repository. Install missing dependencies as specified in the baseline if necessary.
+
 3. Make sure to set the resource directory to the path of your working copy:
- ```smalltalk
-SBEFigureBuilder resourceDirectory: FileDirectory default asFSReference / 'path' / 'to' / 'workingCopy'.
- ```
+
+   ```smalltalk
+   SBEFigureBuilder resourceDirectory: FileDirectory default asFSReference / 'path' / 'to' / 'workingCopy'.
+   ```
+
 4. Install any Linux distribution.
+
 ### II. Building
+
 1. Do it:
- ```smalltalk
-SBEFigureBuilder buildAllTexFigures.
- ```
+
+   ```smalltalk
+   SBEFigureBuilder buildAllTexFigures.
+   ```
+
 2. From the shell, run "make" in the working copy.
 
-For more insights into the build process, have a look at the `Makefile` and the `.travis.yml`.
+For more insights into the build process, have a look at the [`Makefile`](/Makefile) and the [`.github/worfklows/build.yml`](.github/workflows/build.yml).
 
 ## Printing