Bug Reporting
Alpha
Version:9.2.3 - "Suhail"
Last update:2021-05-21 14:43:30



This document explains how to report bugs in an efficient and informative way. See also the file Debugging Help which describes some debugging techniques.

One-line instruction: to report a bug, select the Help ↣ Bug Reports ↣ Create New Ticket… menu item. Read on for more info, specifically in the section Bug reporting.

Introduction

Why report bugs?

Bugs are erratic behaviour of a program. If you experience that Alpha behaves unexpectedly, you may well have run into a bug, and it is important to report it to the developers, to take advantage of the fact that there are human beings behind the program, and they are willing to help. There is a good chance that the bug can be fixed quickly, and when it is, the patch typically becomes available immediately via the Update AlphaTcl mechanism -- no need to wait until the next release! In this way, rather than having to live with the bug, you will have contributed to its elimination, with the obvious benefits for yourself as well as for others. See the Update AlphaTcl help file.
For the developer to fix the bug it is necessary that he can reproduce it, or at least understand precisely what the problem is. For this reason it is important that you describe the bug carefully, and provide certain technical details about the circumstances the bug occurs in. This document explains these things. Once the developer understands the symptoms, he can start debugging it.

What is debugging?

Debugging consists in making experiments to test hypotheses about the origin of the bug, so as to obtain a precise diagnosis of the problem. If the developer can reproduce the bug, then the reporter has little more to do: the developer can conduct the experiments at his own computer. However, it sometimes happens -- especially if the initial report is not detailed enough -- that the developer cannot reproduce the bug. In this case he needs to ask the reporter to help again: he will try remotely to guide the reporter through some further experiments by sending step-by-step instructions to the reporter, who is then requested to observe the outcome of the experiments and report back. Many such instructions are very standard, and they are described in this document. Two of the most common ways to gather the required information is to copy the 'errorInfo' or to perform a stack trace.
How far you go into this depends of course on your interest in helping getting the bug fixed. It can happen that at some point you feel you haven't got the time for more technical experiments and that you just want an editor that works!
Keep in mind, though, that all of the AlphaTcl developers are in similar situations: they are volunteers doing their Alpha development in their spare time without being compensated in other way than their interest in Alpha and their wish to help other users. Most of the developers got into this by first being Alpha users, then gradually becoming more and more interested in the technical details of Alpha... Bug reports that are friendly, coherent, and complete will be much better received, and are more likely to lead to a fix of the bug.

Why does Alpha have bugs?

The easy answer to this question is that the software has not been tested well enough. The reason for this insufficient testing, which is common to most software, is that it is very difficult to predict or even imagine all the circumstances and special situations the software may encounter in real life: it can be one out of a million possible combinations of the preference settings, it can be a document with special features not covered by the tests, it can be a Hungarian keyboard or an Icelandic Date-and-Time setting, or a combination of all such things -- it is very difficult to design tests to take everything into account.
Furthermore, Alpha is rather complicated software with many different behaviours depending on mode and preference settings, and it must be admitted that many bugs are introduced by developers without sufficient overview over all the possibilities: when they try to fix one bug, they may inadvertently introduce another. Typically, analysis of a bug in some mode may reveal that some underlying general technology (e.g. indentation routines or menu handling) is not sufficiently flexible to meet the requirement of this particular mode, and then those general routines are modernised, with the sad side effect that some other bug turns up in some exotic situation in a different mode, for which the original routines were working well :-(

A note on Alpha's innards

It is useful to know that the program Alpha consists of two parts: a compiled C program called the core, and then a big library of supporting script files written in Tcl, called AlphaTcl. The core takes care of low-level stuff like drawing the text in the window, and cursor movements. All the high-level functionality -- the features that characterise Alpha -- is implemented in AlphaTcl. This division of labour means on one hand that the core is relatively small and stable, and does not change much, and on the other hand that all the editing functions are defined in plain text files (residing inside the Alpha application bundle), easily accessible for inspection. This is what makes it so easy to extend and modify Alpha -- and to fix bugs.
The document Debugging Help describes how to do real debugging by looking into the Tcl files, experiment with them, to figure out what is wrong, and fix the problem on the spot. Of course this requires a minimal experience with programming, but one may add that Tcl is one of the easiest scripting languages to read, and before you know of it, you have acquired that minimal experience!

Vocabulary: four main types of bug

Bugs can generally be divided into four types (crash, freeze, error, and silent unexpected behaviour) described thereafter:
crash
This is when Alpha suddenly quits. In this case, the operating system will inform you The application Alpha has unexpectedly quit. Furthermore, there is then a crash log available at ~/Library/Logs/CrashReporter, and it is essential to attach this log to the bug report (but do not attach it if the posting is to a mailing list). Crashes are typically caused by a bug in the core (e.g. some lowlevel error like trying to access a memory register that no longer exists).
freeze
This is when Alpha locks up and becomes completely unresponsive. Typically the cursor becomes a Spinning Pizza Wheel, and it does not help to click anywhere. The only remedy is to force quit the application (by ⌃⌘-Escape). Typically a freeze is the symptom of an infinite recursive loop; this is almost always caused by a bad script in AlphaTcl.
error
This is when Alpha is aware that something went wrong, and reports it in an error message. This message may be transmitted to the user in an alertnote or in the status bar, but the error can also be concealed by the program, in an attempt to proceed with normal operation with fingers crossed. Such a concealed error message can still be inspected, though, as explained in Obtaining 'errorInfo'. Errors are often caused by silly oversights in AlphaTcl scripts, and they are usually easy to fix.
silent unexpected behaviour
This is when Alpha succeeds in completing all the instructions in a script without problems, but that in reality the instructions were not correct. Wrong text manipulations are often of this type: Alpha is told by the script to insert some text content and does this to perfection; the problem was that the text to insert was crafted badly by the script.

Bug reporting

Observing and describing the bug

In order to report or debug a bug, it is important to have a clear description of it. This involves saying precisely what goes wrong (and what was expected to happen), including any status bar messages or alert dialogue information. (If there are no messages or dialogues, state that explicitly.) It also involves describing the exact circumstances, and in particular to indicate whether the bug happens always (under the circumstances) or only sporadically.

Questions to ask (check-list)

Here are some questions it is important to ask oneself before reporting the bug:
  1. in which sense does something not work? Does something wrong happen? or simply nothing happens? What was expected to happen? Is there an error message?
  2. in which mode does the bug occur? is it with a mode-specific operation, or one that can be tested in other modes? and in that case does it happen in Text mode? [Text mode is the most feature-less mode, so if the bug happens also here, then it has probably nothing to do with modes at all.]
  3. does the bug happen independently of which document is being edited? for example, can the bug be reproduced in a new document with only one line of text and saved on the desktop under the name Test? [If the bug happens also in a nearly empty document, then it is not likely to be related to the content of the document, and if the file is called Test and lies on the desktop, then the bug does not have anything to do with strange file names, read-only media, or network connections!]
  4. does the bug happen always, or only sometimes, within the circumstances found in the previous questions? In other words, is the bug replicable?
  5. which version of Alpha are we talking about? Indicate the Version Info
  6. could the problem be related to some local configuration? See the Removing preference files section for how to test this.

Version Info

It is important to identify exactly which version of Alpha you are using while experiencing the bug. Since Alpha has various internal components, there are actually many numbers that might be relevant, and for the beginner it is not easy to know which, and where to find them.
When you create a new ticket to report an issue, it is helpful to provide information about the configuration of your system and of your Alpha application. For convenience, there is a command that gathers all the necessary data. The Help ↣ Bug Reports ↣ Display Version Info menu item collects and displays all the necessary details in a separate window in Alpha so that you just have to copy and paste this information at the end of your bug report.
Alternatively, you can get the version info from the Debugging Palette by selecting Display Version Info.
If your version of Alpha is not the most recent, you should consider to upgrade. Possibly this solves the problem. To find the most recent version, see the Alpha's Home Page or the Alpha Wiki. For a given version of Alpha, it is also possible to update to the latest version of AlphaTcl: this is a simple operation performed via the Alpha ↣ Global Setup ↣ Update AlphaTcl menu (see the Update AlphaTcl help file).
If the problem is gone in the newest version, that's nice of course. If it is not, this is a very valuable information, since the developers are much more interested in bugs confirmed to pertain to the latest version.

Asking the mailing lists

Once the bug is properly observed and has been formulated, it should be reported. A recommended first step is to send a message to the AlphaTcl-users mailing list (or perhaps to the developers list, if it is more technical). See the Readme file for how to subscribe to these lists.
This will trigger some feedback from the developers or from other users who have experienced something similar. Perhaps the feedback will be an explanation saying that this is not a bug at all, but rather a feature, i.e. an intended and documented effect of some preference setting, and you will soon be instructed how to turn this feature off and configure Alpha to your liking.
Perhaps the feedback will inform you that this is already a known bug, and that somebody is looking into a solution. Your bug report may then have the effect of motivating that developer to fix the bug faster, or it may even provide some important new input.
But more typically some developer will acknowledge that this is a bug, and ask you to please file an official bug report (open a ticket) on the bug tracking system.

The bugs tracking system

The bug-tracking database

Alpha has a sophisticated on-line bug-tracking database referred to as Alpha's Bug Tracker, in which all bugs and feature requests are entered and stored. This database contains for each bug the original report together with all subsequent comments made concerning the issue, narrowing down the bug, suggesting workarounds, possible relations with other bugs, and eventually its fix and resolution.
The Alpha project is hosted by SourceForge and uses the tracking system installed on this platform at the following address: Alpha's Bug Tracker.
See the Bugs Tracker Help for more information about this bug reporting system. Note that it requires that you be a registered user at SourceForge as explained in the Tracker Registration section.
Bug reports, requests for enhancement and requests for a task are all referred to as tickets. All the tickets are identified by a unique number. You can find a complete documentation about the tickets system on the following page: https://sourceforge.net/p/forge/documentation/Tickets/.
It is important to use this facility, since bug reports made by email tend to be forgotten, and it is a big job to search old mail archives to find comments. Using the Alpha's Bug Tracker system will help us (and you) to keep track of all information related to the issue. Here is the URL of https://sourceforge.net/p/alphacocoa/tickets/.
Bugs are fixed as soon as possible -- how long it takes may depend on the precision of the report. Some bugs that have an obvious solution will be fixed on the same day that they are reported. Others, which cannot be easily replicated or require a more thorough examination to discover the underlying cause of the problem, might retain a NEW or UNCONFIRMED status for quite a while. Some bugs have been waiting years for a proper fix -- but so long as they are properly entered into the database they are never truly forgotten.

Known bugs

In order to determine if an issue has already been reported or if a request for enhancement has already been submitted, you should have a look at the existing reports (aka tickets) in the database. To see all the tickets in the database, go to Alpha's Bug Tracker.
From Sept 2002 to Jan 2010, AlphaTcl used a bug tracking system called Alpha-Bugzilla. It has now been closed, but an archive of its 2403 reports has been installed online for reference at the following address: Alpha-Bugzilla.
Note also that the Changes - Alpha and Changes - AlphaTcl help files, a summary of the history of Alpha's development, might mention the bug, with information about partial or complete fixes, and often with reference to Alpha's Bug Tracker. These files are accessible from the Help ↣ Developer Help menu.

Creating New Ticket

To file a new ticket, click on this hyperlink: report a bug. This command is always available by selecting the Help ↣ Bug Reports ↣ Create New Ticket… menu item or from the Debugging Palette.
This will prompt you with a few choices in a dialogue: in the field Type there are three options: Bug, RFE (request for enhancement), and Task. This document is mostly concerned with bugs, so it is assumed you should choose Bug. But the bugs tracker is also a very valuable tool to keep track of feature requests (RFEs), and of course if you have an idea on how Alpha could be improved, you are very welcome to file an RFE suggesting the improvement. (Other fields ask you to choose a component, a version number, a priority, and other things. Don't bother with these: the default values are probably correct, and otherwise a developer will revise this info later on.)
Clicking OK will open a New Ticket page in your web browser, but you may first be redirected to a registration page: before you can actually enter the bug in the database, it is necessary to register at SourceForge. See the Tracker Registration section.
Once you are at the New Ticket page, specify a one-line summary, and copy your report into the Description field.
You must enter a title for the ticket in the Summary field. Then you should give a detailed description of the bug or the request in the Description field. You may use WikiFormatting in this field.
You should also set appropriately the popup menus displayed under the Description field:

Source Code Browsing

The platform at SourceForge also provides facilities for browsing the Subversion repository where the source code of Alpha (both the core and the AlphaTcl library) is kept and developed. It is accessible at the following address: Subversion Repository Browser.

The Bug Reports menu

The Bugs Tracker package in Alpha's library provides basic support for communicating with the tracker system. This package is always on so there is no need to activate it explicitely.
Inside Alpha's Help menu, you can find a submenu named Bug Reports. It contains items which give you a quick and easy access to the Web pages of the Bugs Tracker.
The Help ↣ Bug Reports ↣ Create New Ticket… menu item will open a window in your favorite browser in which you can type your report.
Once again, you must be logged in at SourceForge to create a new ticket. If it is not the case, you'll find a link in the page displayed by your browser to log in (see the Tracker Registration section).
The Bug Reports menu has items to display help files in Alpha's Help Viewer or accessing the mailing list archives or the old Alpha-Bugzilla database.

Viewing existing tickets

To simply read already existing tickets, you do not have to be a registered SourceForge user. You can just go to the Alpha's Bug Tracker using the Help ↣ Bug Reports ↣ Go To Bugs Tracker menu item. On the other hand, if you want to edit a ticket and enter comments, the Edit button will be present only if you are logged in.
The Bug Reports menu has useful items to view existing tickets:
View A Ticket…
this menu item lets you access any already existing ticket. You just have to specify the number of the ticket you want to open
View Active Tickets
this menu item displays in your browser a list of all the currently opened tickets.
View Closed Tickets
this menu item displays a list of all the currently closed tickets.

Credits and Copyright

Author: Joachim Kock, with many snippets from earlier help files. This document has been placed in the public domain.