How to contribute to Squeak
Last updated at 2:42 pm UTC on 8 March 2020
Squeak is maintained by volunteers around the world using a simple community driven process known as the Development Process
Contributions may take different forms.
- One may fix a defect in code or help text,
- create new graphical elements like icons or fonts,
- extend the base system with new frameworks
- or even build a whole application package.
See section below for detailed steps.
Squeak has a built-in package management tool called Monticello that makes it very easy to gather and upload a ChangeSet to repositories.
Many packages also use Monticello for version control. It started with http://www.squeaksource.com/ as the repository which is still in use. Newer projects are hosted at SmalltalkHub and SqueakSource3 (ss3).
Contributing to the Base system
If you want to contribute an improvement you can submit it to the Inbox repository. Developers on the squeak-dev mailing list will be notified and the change might be discussed there. Accepted changesets are merged into the main trunk by Core Developers and the rest are moved to Treated repository.
Contributing Bug Fixes
- Commenting Bugs and Fixes is where you can help even if you're completely new to Squeak. For example, if you had a problem, asked on the mailing list, and someone more experienced fixed it, you could help out by commenting bugs and fixes.
- Reporting Bugs and Fixes explains what to do if you find or fix a problem, or want to improve functionality in the image.
Contributing a package
SqueakMap If you write a cool package, this is where you should place it. This catalog allows anyone to install your code easily from Squeak.
Detailed steps for submitting a changeset to the Squeak Trunk Version
... adapted from Dave Lewis post in squeak-dev mailing list
At any given time, there will be a release version and a trunk version listed in Squeak Downloads. Changes may be proposed to the latest version under development by following the steps below.
- Create an account on source.squeak.org
- Using a web browser, go to http://source.squeak.org.
- On the left side of the web page, click on "Register Member".
- Fill in the information on the form. In the "Initials:" field, use your regular author initials, same as for method stamps.
- Click "Save".
- Remember the password that you just defined, because you will use it in the next step below.
- Open the inbox repository
- In your Squeak 5+ image, open a Monticello Browser.
- If you don't see http://source.squeak.org/inbox as a repository in the right hand pane of your Monticello browser, add it:
- Click on +Repository
- In the dialog, change "http://source.squeak.org/inbox" in the location, put your author initials in the "user" field, and put your new password in the "password" field.
- Click "Accept"
- Verify that http://source.squeak.org/inbox now appears as a repository.
- Verify the differences between your image and the latest version in the trunk repository:
- Update to latest version (world -> help... -> update code from server)
- In the Monticello browser, highlight your package on the left, and repository "http://source.squeak.org/trunk" on the right.
- Click the "Changes" button on the top.
- Verify that these are the changes that you want to submit, no more and no less.
- If you see extra changes, open trunk repository and look for new changesets (underlined) for this package. Merge them before proceeding further.
- Use Change Sorters to split or merge changes into different sets. If something looks wrong, stop and ask for tips on the squeak-dev list.
- Submit your changes to the inbox
- Make sure your package is selected in the left pane
- If the inbox repository does not appear in the right pane,
- Right click on the package and select "add repository..." and pick the inbox from the popup menu
- Now select the "http://source.squeak.org/inbox" repository on the right pane of the Monticello browser
- Click the "Save" button on the top of the Monticello browser.
- In the save dialog window that opens now, verify that the changes listed on the left panel are what you would like to submit.
- Edit and replace "empty log message" text on the right panel with your patch description. The patch gets sent to the mailing list, so put enough information for core-developers to pick this commit for review. If the patch emerged from a discussion in mailing list, add a link to the thread.
- Click "Accept"
- Wait for the changes to be sent to the inbox repository.
- Follow ups
- Your new update should now appear in the inbox. In the Monticello browser, highlight the inbox repository and click the "Open" button at the top. A Repository Browser will open. Click the "Refresh" button, and you should see your new entry listed. You can also find in through the web interface for http://source.squeak.org.
- On the squeak-dev list, a mail notification should appear within a few minutes to notify the list about your new submission.
- You can reply to that notification on the list, or to your earlier mail thread to offer any other explanations or to ask someone to look at your inbox submission and move it to trunk (or to "treated inbox" if it is not suitable for trunk for some reason).
A good commit message should state what was changed, why and possibly include a small code snippet to explain the reason for the change. Someone, a few years down the line, should be able to read the patch and understand why the change was made. See http://forum.world.st/The-Trunk-Compiler-eem-387-mcz-tp5079866.html for an example.
Merging Commits from the Inbox by Core Developers
If a change in the inbox is accepted the following should be done by a core developer to merge it:
- Merge the commit in an up-to-date trunk image
- Make sure the commit works with the up-to-date image
- Commit the merged state
- The merge commit has now two ancestors: the previous head of the trunk repository and the commit from the inbox. To provide a consistent history, we have to move the inbox commit to the trunk repository. Therefore go to Inbox and look for the commit under versions. After clicking on the version you see details of the version and two buttons which allow you to move the version either to trunk or the treated inbox. Use the move to trunk button to move the change to the trunk.
In case there are no new commits in the trunk repository, core developers can also simply use the "Move to Trunk" button on http://source.squeak.org/inbox.
If a changeset (say badfix.101) has been merged into trunk from inbox and later discovered to be defective, then
- Create a new changeset (say goodfix.102)
- Create a new merge (say mergedfix.105) that contains the fix and has both badfix.101 and goodfix.102 as ancestors
This will preserve the history for those who would have upgraded from the trunk meanwhile.
Guidelines for Core Developers for Trunk submissions:
- Give your peers a chance to review, commit to the Inbox first.
- Regard the code repository and ancestry with equal respect to the image, for example, by avoiding unnecessary litter and bloat.
- Never only change formatting, and even avoid changing prior developers formatting when making only minor changes to a method.
- Never commit same-day code. Think about it and live with it for at least a few days first.
- Only commit meaningful changes like a fix or improvement, not merely a spelling or comment fix. Gather those up to include next time there is a bigger change to that package.
- Before moving something from Inbox to Trunk, please re-adopt the version in trunk as the ancestor, so the ancestry will not be bloated with all of the interim attempts – the goal is one version per change.
Note: The "Adopt" button currently produces an intimidating message, but it's really okay to use in this instance.
- If you mess up, and its still the top version, revert to the prior version before applying the fix.
- When saving the MCZ version,
- Arrow through every single change and review it.
- Use the description to explain why the change is being made rather than what.
- Keep it short – don't put explanations of things that don't need explained, like obvious corrections (spelling, etc.).
- Remember to consider all the other "objects" of the MCZ besides just the code and description, specifically, there are the pre and post scripts, as well as the MCZ name.
- Try to never use the same MCZ name for two different versions. The repository's expect fully unique names, duplicate names for different changes will lead to headaches.
- Consider batching up trivial improvements (i.e., a fixed misspelling of a comment) together and/or piggy-backed with other non-trvial change within that same package.
Repository Locations
More
