How to Report a New Squeak Issue

This document attempts to clarify the process of submitting a bug report, fix, or enhancement to the Mantis database.

The first thing you must do is to pick the correct project. Currently Squeak issues are split between two projects: 'Squeak' and 'Squeak Packages'.

The difference between the two projects is based on whether the issue is related to code and objects that would be found in the Full version of the Squeak image (downloaded from squeak.org) without any further packages loaded or whether the issue resides in a package that would not be found in a Full version of the Squeak image. The 'Squeak' project is for any issue with a standard Full Squeak image. The 'Squeak Packages' project is for any other issue.

If you are uncertain which is the appropriate project then first try the 'Squeak' project. If after examining the Category list (discussed below) you are unable to find an appropriate category then try the 'Squeak Packages' project. If you still don't find an appropriate category then simply report the issue to either project and choose 'Any' as the category. Someone else will move and recategorize the issue as needed.

When you click the 'Report Issue' link in the menu at the top of any page you may be presented with a page that looks like diagram A to the right. You will generally see this if you have not previously selected a project or have selected 'All Projects'. Choose the appropriate project name from the 'Choose Project' drop down box and hit the 'Select Project' button.

If you have previously selected a project you will almost certainly be immediately presented with a form to fill out like that shown in diagram C below. If this is the case then look at the top right of the page for the project switch drop down as show in diagram B to the right. By default the drop down should have your current project selected. If this is not the project you want or you just want to be sure that the correct one is selected then choose it from the drop down. In most browsers the project should immediately change. If it does not for you then click the 'Switch' button. If necessary hit the 'Report Issue' link in the menu again to get the issue reporting form.

Once you have selected the appropriate project then your first task is to select the category to which your issue applies. Take a look at the list available in the Category drop down list (at 1 in diagram C). In general the categories either name a category as can be seen in a Squeak browser in the left panes or a package as can be found on SqueakMap. In many cases multiple related packages will be combined into one category for the listing on Mantis. For example there are several packages related to the code for the SqueakMap server and the SqueakMap Package Loader but on Mantis these are all considered simply to be the Category 'SqueakMap' which can be found in the 'Squeak' category.

If you don't find an appropriate category check the other project to see if it is listed there. If you still are unable to find it simply choose 'Any' and at a later time someone will recategorize it creating a new category if necessary.

One useful piece of information concerns the difficulty of reproducing the issue. Try to make an appropriate choice to the best of your ability from the Reproducibility drop-down list (at 2 in diagram C). If this is not a bug then 'N/A' is probably the appropriate choice.

Next try to give some idea of how important you believe this issue is. Choose a designation from the Severity drop-down list (at 3 in diagram C).

If you are reporting a bug you will generally choose from 'minor', 'major', or 'crash'. Only choose 'crash' if the issue causes the VM to exit catastrophically.

If you are submitting a fix or an enhancement you will choose either from the list for bugs or from 'feature', 'text', 'tweak'. If you are submitting an enhancement that adds a new feature then choose 'feature'. If you are correcting a textual typo or perhaps adding just a small amount of new text then choose 'text'. If you adjusting an existing feature but not fixing a bug then choose 'tweak'. If you think your submission is truly trivial then feel free to select 'trivial'.

The 'block' choice is generally used by the developers to designate an issue that must be fixed before the next release. This is a difficult decision to make and in general a reporter will not use this designation.

In general you do not need to select a priority and the default choice of 'normal' is fine.

This is optional and not even available for all projects. The version here refers to the version of Squeak to which this issue relates. If this field is available then select the version of Squeak you saw the bug in or to which your attachment applies from the drop-down list (at 5 in diagram C). You can discover the version of a Squeak image by choosing the 'help...' menu item from the World Menu (generally produced by clicking on the background), then choosing the 'about this system...' menu choice.

Think of this field like the Subject of an email. Write a very short one line description of the issue.

This is probably the most important field of the entire form. In the Description field (at 7 in diagram C) you will describe in as much detail as possible either the problem you have discovered or the fix or enhancement you are providing.

If you are reporting a bug it is very important that the developers understand how to reproduce the issue. Give as much detail as you can about the environment in which you experienced the problem:

• What platform and operating system were you running Squeak on?
• What version of Squeak were you using? You can check the version of the image by choosing 'help...' then 'about this system...' from the world menu. On many platforms you can check the version of the VM by running it with the '-version' option from the command line.
• What packages do you have loaded? You can discover this by opening the SqueakMap Package Loader (found in the World menu under the 'open...' sub menu) and bringing up the context menu for the pane at the left that lists the available packages and ensuring that only the 'display only installed packages' filter is enabled in this menu. If that is the case then the list of packages in the middle pane at left is your installed packages and the versions. You can put a copy of this list in the copy/paste buffer by selecting 'put list in paste buffer' from the context menu which should make it easy to paste this information into the description.

If you can please try to reproduce the issue in the very latest available image fully updated and with no extra packages loaded.

Next describe the steps you took that led to the issue. Be detailed. And of course as clearly as you can describe the problem.

If you are providing a fix for a problem either refer to another Mantis issue by its ID number where the issue is described or describe it in complete detail yourself as discussed above. Alternatively you might find it simpler to just add your fix to the original report and not fill out a new report. Of course if you do so please add any additional information that you have in the note.

If this is an enhancement then describe how it would be used and any requirements such as required packages. Feel free to present your argument as to why you feel that your enhancement should be incorporated into a future version.

The Additional Information field (at 8 in diagram C) is optional but is where additional information such as a debug log can be provided.

This is also optional but of course if you are providing a fix or enhancement then it should be attached here (at 9 in diagram C).

If this is meant to go into the base image then it should be a changeset that is gzipped. External packages may have other preferences and you should probably contact the developers to find out what they prefer.

Ignore the 'View Status' field and unless you have another issue to report you can skip the 'Report Stay' field (if you do just check the checkbox) and hit the 'Submit Report' button.

You're Done! Thank you for your report and all your future reports.