SqueakMap Publishing Guidelines


	links to this page:

Last updated at 8:30 pm UTC on 6 April 2021

Introduction

SqueakMap started out very useful and very popular. Initially, all packages ever created in SqueakMap were shown in the list. Over the years, as the community experienced churn, severe bit-rot set in, causing the vast majority of the listed packages to not work. This spoiled SqueakMap's usefulness and, eventually, its reputation, and left the Squeak community with no coherent-and-consistent way to publish and share software with the world.

Adhering to some basic guidelines when publishing our projects, our Community Requirements for a Software Catalog can essentially be met today, despite the fact there are many many improvements that can and should be made to the entire SqueakMap codebase.

Guidelines for naming release versions

There are two types of releases to create for a package. Ideally they should both be created. But if only one is created, it should be the fixed-configuration script, not the head script. Otherwise, it will suffer from bit-rot.

A fixed-configuration is simply an install script that loads specific versions of specific MC packages into a specific release of the Squeak image. It is created for longevity. It can be named anything but "head".
The head release should only be created if a fixed-configuration has already been created. It is used to allow the most-active and interested users to keep up with the latest code with one-click. The head release should be named "head". When users install this version it goes through the prerequisite tree of that package and performs a trunk-style merge of all the latest packages.

Guidelines for writing the script for a fixed-configuration

The minimum requirements of a fixed-configuration script are:

Load all immediate SqueakMap prerequisites. (The immediate prerequisites will load their immediates and so on). Note to load a particular release of a particular package:

	SMSqueakMap default 
		installPackageNamed: 'Your SM Package Name' 
		version: 'release name'

Do not load any immediate prerequisites which may already be loaded in the image. (This gives some flexibility to developers / daring-users in case they've got their own "custom" version of a pre-req loaded, while not spoiling the longevity requirement).
Write the script (using your favorite installer utility) to load the individual MC versions for that package.

For example:

	"Load Ma client server package if not already loaded."
	(Smalltalk hasClassNamed: #MaClientSocket)
		ifFalse:
			[ SMSqueakMap default installPackageNamed: 'Ma client server' version: '1.5' ].

	#('WriteBarrier-cmm.35.mcz' 'SOLHashTables-cmm.16' 'Magma-Client-cmm.605' 'Magma-Squeak-Client-cmm.3') do:
		[ : each | (Installer repository: 'http://www.squeaksource.com/Magma') install: each ]

Guidelines for writing the script for the head release

The head release should merge all the packages into the existing image without stomping any of the local changes. To do this you must have created a Monticello Configuration named "update" in your SqueakSource project (note the "copy image versions here" convenience menu item saves a lot of tedious time!).

The script is almost the same as the script for fixed-configurations.

Load the 'head' release of all immediate SqueakMap prerequisites.
Do not load any immediate prerequisites which may already be loaded in the image.
Write the following to merge the "update" Configuration on SqueakSource, just as it is done in our trunk process:

	MCMcmUpdater updateFromRepositories: #('http://www.squeaksource.com/ProjectName').

For example:

	"Merge the latest Ma client server code (a prerequisite)."
	SMSqueakMap default 
		installPackageNamed: 'Ma client server' 
		version: 'head'.

	"Merge the latest Magma client packages."
	MCMcmUpdater updateFromRepositories: #('http://www.squeaksource.com/Magma').