Filing a report

In order to file a report of a problem with Gnumeric, a GitLab account is necessary. Please see the previous section, Section 17.3 ― Opening an account, for an explanation of how to open an account.

The Gnumeric bug entry page consists of several fields many of which must be filled out to provide a useful bug report. The most important of these will be the "Bug Description" which contains both the brief "Summary" field which acts like an email subject line and the detailed description field "Step to reproduce the bug" which should be used to give a more complete explanation of the problem and, ideally, to describe step by step how to reproduce the bug. The only other field which is required is the "Component" field which can be set to "General" and left to the developers to define more specifically. The remaining fields can be helpful, since they provide extra information which may help resolve the problem, but are not necessary. After filling out these three fields, a user can, if they desire, simply skip to the bottom and press the Commit button.

17.4.1. Accessing the GNOME project's GitLab

There are several ways to file a bug report through GitLab.

One of the entries in the Help menu is called Report a Problem. This menu entry should cause a browser window to launch and open GitLab to the Gnumeric page.

Alternatively, users can click on this link to access the Gnumeric page in Gitlab.

If neither of those shortcuts work, the user must use a web browser to access the following location:
The simplest way would be to use the mouse to copy the text and paste that text into the location bar of a web browser.

The user may be asked to login, by giving their account name and their password, when they begin their browser session with GitLab. See Section 17.3.2 ― Logging into the account for an explanation of how to login to GitLab.

17.4.2. The Bug Description

A useful error report will include a subject that describes the error concisely, has a brief introduction which explains in greater detail what happened and, ideally, has a small recipe that leads to the error being repeated.

The summary field, like the subject of an email message, briefly describes the problem. For example, a useful error report might have a summary "Gnumeric crashes when saving a file".

The field titled "Steps to reproduce the bug" should contain a slightly expanded version of the summary giving an overview of the problem and then give a step-by-step example of how to reproduce the problem. For example, this field could look like the following:

This report describes an error which causes Gnumeric to crash
during the use of the file save dialog.

1) Start a new Gnumeric
2) In Cell A1 type "hello"
3) From the "File" menu, select "Save As"
=> The "Save As dialog" opens up
4) In the file name box, type "my_spreadsheet.gnumeric"
5) Click on the "Save" button
=> I expected the file to be saved, and to be able to keep
working but instead Gnumeric disappeared and the file was 
never saved.

a user

17.4.3. Product and Component

The Product should be set to Gnumeric since the GNOME version of GitLab is used for all the different programs in the project.

The Component describes the part of Gnumeric that causes the problem. This may not be obvious so, unless one of the other entries clearly matches, the component should be set to "General". The possible components for Gnumeric are as follows.

Table 17-1Components of Gnumeric
Component Explanation
Analytics Problems with calculations and other mathematics.
Charting Problems with graphical plots of worksheet data.
Compilation Problems encountered during source code compilation.
Database plugin Problems when using a database from Gnumeric.
Documentation Problems with this manual, with the explanations of functions, or with any other explanations.
General The Default. Use this when none of the other categories apply.
GUI Problems with the graphical user interface.
GUI Expression Entry Widget Problems while entering or editing cell contents.
import/export Applix Problems opening or saving a file to the file format used by the Applix spreadsheet.
import/export HTML Problems opening or saving a file to the HTML or LaTeX file formats.
import/export MS Excel (tm) Problems opening or saving a file to any of the various file formats used by the Microsoft Excel spreadsheet.
import/export OOo / OASIS Problems opening or saving a file to the OASIS file format used by OpenOffice.Org Calc or Star Office Calc.
import/export Text Problems opening or saving a file to a text file format including tab, comma and space delimited files.
Installation Problems encountered during Gnumeric installation.
Main System This component is no longer used.
Printing Problems encountered when printing a worksheet.
Sheet Objects Problems with any images, widgets, or drawing elements added to a worksheet.

17.4.4. The Severity and Priority of the Problem

The severity level indicates the seriousness of the problem and the priority level indicates the desire of the developers to address the bug. These fields are used mostly by the developers and should both be left as "normal" unless the user has a good reason to change them.

There are two cases when the user should change the severity of the report. In the first case, if the user has a problem which causes Gnumeric to crash (to suddenly disappear or stop working) or a problem in which data is lost, the severity should be set to "critical". In the second case, if the user has a report about a desired feature, the severity should be set to "enhancement" so the developers will know right away that the desired functionality has not yet been added to the program.

The problem severity levels are explained below.

Table 17-2Problem Severity
Severity Level Explanation
blocker The level used to indicate a problem which must be fixed before any next release.
critical The level used to indicate a very important problem such as a program crash or loss of data.
major The level used to indicate a severe problem but one that does not cause a crash or loss of data.
normal The level to use by default and used for the majority of reports.
minor The level used for problems which do not affect the functioning of the program.
trivial The level used to report typos, aesthetic, and other very small problems.
enhancement These are reports which are requests for future improvements of the program.

The priority level should be left at the "normal" level since this is a field used by the developers themselves.

17.4.5. The Version of Gnumeric and GNOME

The version field is used to indicate the version of Gnumeric which was used when the problem occurred. If the problem occurs with several versions, the most recent version number should be used. The version number can be obtained by opening the "About Gnumeric" dialog using the Help menu and the About menu item.

The "GIT" version refers to a version which the user has recently obtained from the Git revision control repository provided by the GNOME project.

The "Other version details" text box can be used to describe any unusual characteristics of the program such as plugins which were added or other uncommon modifications.

If Gnumeric is being used with a GNOME desktop, the version of GNOME being used can be entered in the "Gnome Version" field.

17.4.6. The Type of Operating System and Distribution

The "Operating System" field can be used to describe the underlying operating system being used to run the Gnumeric program. Please note, that if the program is run in an artificial environment such as a virtual machine or a Cygwin setup, this should be indicated in the next field.

The "Distribution/Version" field should be used to add detail to the operating system described earlier.

17.4.7. Other fields and keywords

These fields are used by advanced users to better sort through all the reports. The "Keywords" field is used to relate the reports to each other and the "CC" field is used by those who are interested to add themselves to those who are notified when changes are made to the report.

17.4.8. Submitting the report

In order to submit the bug report into GitLab, once all of the important fields have been submitted, simply click on the Commit button.

Once the bug is committed, a bug report number for this bug will be assigned, and email will be sent either the project maintainer or to one of the other developers which deal specifically with that component of the program. When others take an interest in the bug and add comments or solutions, email will be sent out to the user to inform them of the status of the bug until it is either dismissed or resolved. Bugs can be dismissed if they describe a behaviour that is expected or if they are not deemed important enough to fix.

A user can choose not to be notified when changes to reports are submitted. The user preference page can be accessed here at the following URL.

17.4.9. Bookmarking a template

A version of the bug entry page with most of the fields already filled out can be saved as a link and bookmarked for future use. This ability is only of use for developers or for users who have found a large number of bugs in one particular component of Gnumeric.

To use this shortcut, first open a new bug report, then fill out only the fields that will apply to all the future bugs being reported and then click on the button labelled "Bookmark these values". GitLab will then construct a template and will provide a link which can be saved for future use just as any other page on the web can be saved as a bookmark. To use these values, simply clicking on the bookmark will open the Gnumeric page of GitLab with the common fields already filled out.