Merge pull request #189 from hpi-swa-lab/squeaksource

Add relevant packages to SqueakSource

FirstApp/FirstApp.tex

@@ -835,9 +835,9 @@ \subsection{Saving and loading code with Monticello}
 
 \subsection{\ind{SqueakSource}: a sharing platform for Monticello}
 We think that the best way to save your code and share it is to create an account for your project on a SqueakSource server.
-SqueakSource is like GitHub\footnote{\url{www.github.com}}:
+SqueakSource is similar to GitHub\footnote{\url{www.github.com}}:
 It is a web front-end to an HTTP Monticello server that lets you manage your projects.
-There is a public SqueakSource server at \url{http://www.squeaksource.com}, and a copy of the code related to our game is stored there at \url{http://www.squeaksource.com/QuintoExampleSBE.html}.
+There is a public SqueakSource server at \url{http://www.squeaksource.com}, and a copy of the code related to our game is stored there at \sbeSqueaksourceUrl.
 You can look at this project with a web browser, but it's a lot more productive to do so from inside \squeak, using the Monticello browser, which lets you manage your packages.
 
 \dothis{Open a web browser to \url{www.squeaksource.com}.

README.md

@@ -101,6 +101,37 @@ For more insights into the build process, have a look at the [`Makefile`](/Makef
 The book has been reformatted to 6"x9" (for Lulu). If you want to print any
 part of the book, you will find that printing 2 up at 140% works well.
 
+## Release Process
+
+### 1. Actual release
+
+- Make sure the CI is green.
+- Check the relevant PDF from the latest prerelase manually for any slips (i.e., search for `missing figure` and `??`, check for layout quirks, maybe scan the build log for warnings).
+- Trigger a new release from the <kbd>Actions</kbd> tab of the GitHub repository and update the settings:
+
+  ![GitHub Actions: Run workflow](gh-actions-release.png)
+
+  - Tick the `Draft` checkbox.
+  - Specify the Squeak version for the intended edition only (e.g., `["6.0"]`).
+  - Increase the scale factor to `10` at will.
+
+  Wait for the CI workflow to complete (might take 10 - 20 minutes depending on the scale factor) and recheck the PDF to be sure (esp. for a different scale factor, some figures could look different).
+
+- Update the sources in the SqueakSource repository (see [SmalltalkSources](#smalltalk-sources)).
+- Select the draft release from the <kbd>Releases</kbd> section on GitHub, edit it, and publish it.
+- Publish the PDF using Lulu or whatever else (maybe we should document this process here as well).
+- Announce the new release on the mailing list, squeak.org, etc.
+
+### 2. Prepare the repository for the next edition
+
+- Secure the current state of the book in a new release branch (e.g., `release/6.0`).
+- Replace the old version with the new version in the CI scripts.
+- Drop support for the old edition from the default branch:
+  - Search the tex sources for all occurrences of `\SqVersionSwitch` and replace them with the argument for the latest version.
+  - Search the Smalltalk sources (`*.{st,cs}`) for version switches (`(>=|<=) Squeak`) and replace them with the latest version.
+  - To be sure, search the entire book for mentions of the old Squeak version.
+- Update the copyright notice.
+
 ---
 
 # Style Rules
@@ -212,12 +243,14 @@ When the `make` command is run, the bibliography is automatically built as well.
 
 # Smalltalk Sources
 
-The "Squeak by Example" Monticello Repository can be found as a [FileTree](https://github.com/dalehenrich/filetree) repository in the `SmalltalkSources` folder.
+The "Squeak by Example" Monticello Repository can be found as a [FileTree](https://github.com/dalehenrich/filetree) repository in the `SmalltalkSources` folder but is best loaded and saved using [Squot](https://github.com/hpi-swa/Squot).
 
-The package SBE-Testing includes as dependencies the code for the hands-on chapters.
+The package `SBE-Testing` includes as dependencies the code for the hands-on chapters.
 It will run all the test code in the latex sources and exercise the hands-on code.
 
-The repository was previously hosted on [squeaksource](http://www.squeaksource.com/@QJbXgqmsC7AwLgNB/jkjcsr-2).
+All packages that contain examples relevant to the user are also hosted at SqueakSource at <http://www.squeaksource.com/SqueakByExample60/>.
+Before releasing a new edition of the book, make sure to update these sources using the `SBESqueaksource` class from the `SBE-Extract` package.
+The SqueakSource repository is world-readable and can be written by the administrators, which are currently ct and pre.
 
 # Coding Style Guide
 

SmalltalkSources/SBE-Extract.package/MCVersionNameAndMessageRequest.extension/instance/resumeMessage..st

@@ -0,0 +1,6 @@
+*SBE-Extract-handling
+resumeMessage: aMessage
+
+	^ self
+		resumeMessage: aMessage
+		excluding: #()

SmalltalkSources/SBE-Extract.package/MCVersionNameAndMessageRequest.extension/methodProperties.json

@@ -3,5 +3,6 @@
 		 },
 	"instance" : {
 		"resumeExcluding:" : "ct 12/2/2019 17:00",
+		"resumeMessage:" : "ct 6/12/2023 22:18",
 		"resumeMessage:excluding:" : "ct 12/2/2019 17:01",
 		"resumeName:message:excluding:" : "ct 12/2/2019 17:00" } }

SmalltalkSources/SBE-Extract.package/SBESqueaksource.class/class/extractToRepository..st

@@ -0,0 +1,6 @@
+extracting
+extractToRepository: aMCRepository
+
+	^ self
+		extractToRepository: aMCRepository
+		message: 'Updates sources.'

SmalltalkSources/SBE-Extract.package/SBESqueaksource.class/class/extractToRepository.message..st

@@ -0,0 +1,14 @@
+extracting
+extractToRepository: aMCRepository message: message
+
+	aMCRepository cacheAllFileNamesDuring: [
+		self packageNames do: [:packageName |
+			| workingCopy version |
+			workingCopy := MCWorkingCopy forPackage: (MCPackage new name: packageName).
+			self assert: (workingCopy possiblyNewerVersionsIn: aMCRepository) isEmpty.
+			version := [workingCopy newVersion]
+				on: MCRepositoryRequest
+				do: [:req | req resume: aMCRepository]
+				on: MCVersionNameAndMessageRequest
+				do: [:req | req resumeMessage: message].
+			aMCRepository storeVersion: version]].

SmalltalkSources/SBE-Extract.package/SBESqueaksource.class/class/extractToRepositorySBE60.st

@@ -0,0 +1,6 @@
+extracting
+extractToRepositorySBE60
+
+	^ self extractToRepository:
+		(MCRepositoryGroup default repositories
+			detect: [:each | each description = 'http://www.squeaksource.com/SqueakByExample60'])

SmalltalkSources/SBE-Extract.package/SBESqueaksource.class/class/knownIssues.st

@@ -0,0 +1,9 @@
+as yet unclassified
+knownIssues
+	self flag: #todos.
+	"
+	* At least I (ct) had problems writing to the Squeaksource, so I temporarily enabled global write access for writing
+	* Version numbers are not always monotonically incremented. Not sure why this is, but deleting the files from the package cache and unloading the packages from the image helped me to reset most of the version numbers.
+	* Might automate this later as part of the CI
+	* Add support for upcoming editions in the future
+	"

SmalltalkSources/SBE-Extract.package/SBESqueaksource.class/class/packageNames.st

@@ -0,0 +1,4 @@
+accessing
+packageNames
+
+	^ #('SBE-Environment' 'SBE-Monticello' 'SBE-Morphic' 'SBE-Quinto' 'SBE-Streams')

SmalltalkSources/SBE-Extract.package/SBESqueaksource.class/methodProperties.json

@@ -0,0 +1,9 @@
+{
+	"class" : {
+		"extractToRepository:" : "ct 6/12/2023 22:20",
+		"extractToRepository:message:" : "ct 6/12/2023 22:19",
+		"extractToRepositorySBE60" : "ct 6/12/2023 22:22",
+		"knownIssues" : "ct 6/13/2023 09:42",
+		"packageNames" : "ct 6/12/2023 22:11" },
+	"instance" : {
+		 } }

SmalltalkSources/SBE-Extract.package/SBESqueaksource.class/properties.json

@@ -0,0 +1,14 @@
+{
+	"category" : "SBE-Extract",
+	"classinstvars" : [
+		 ],
+	"classvars" : [
+		 ],
+	"commentStamp" : "",
+	"instvars" : [
+		 ],
+	"name" : "SBESqueaksource",
+	"pools" : [
+		 ],
+	"super" : "Object",
+	"type" : "normal" }

SourceControl/SourceControl.tex

@@ -227,7 +227,7 @@ \subsection{Basic Monticello}
 \needlines{4}
 \begin{code}{}
 MCHttpRepository
-	location: 'http://squeaksource.com/SqueakByExample'
+	location: '!\sbeSqueaksourceUrl!'
 	user: ''
 	password: ''
 \end{code}

common.tex

@@ -118,6 +118,7 @@
 \newcommand{\sqmap}{SqueakMap\xspace}
 \newcommand{\squeak}{Squeak\xspace}
 \newcommand{\sbeRepoUrl}{\url{https://github.com/hpi-swa-lab/SqueakByExample-english}\xspace}
+\newcommand{\sbeSqueaksourceUrl}{\url{http://www.squeaksource.com/SqueakByExample60}\xspace} % FOR LATER: use \SqVersionSwitch here
 \newcommand{\hpiswa}{\url{hpi.de/swa}\xspace}
 %=============================================================
 %:Markup macros for proof-reading