# Overview

&gnum; is a complex computer program and therefore necessarily contains some mistakes. The &gnum; team is keenly interested in finding these errors and correcting them. Suggestions for improvement are also welcome and can be submitted in the same fashion as an error report.

Please, help us to fix any errors by telling us about them.

Reports of problems with &gnum; provide the project with a way of making sure that the mistake is eventually fixed. Often the mistake is obvious and a fix can be made immediately to be included in the very next release of &gnum;. Occasionally, the mistake is more complex and the problem may take a while to be resolved. In these cases, the report provides a way to remind the developers that the problem still exists.

Mistakes in programs are often called "bugs" after one of the earliest errors in an old machine which was actually caused by an insect entering the machine and preventing a switch from closing.

The &gnum; project uses a world wide web system called GitLab to collect reports of program errors and then to track these errors until they are finally fixed. The system was developed as part of the Mozilla web browser project, which explains the origin of the strange name.

The process of submitting the report of a problem or of a suggested enhancement is quite simple and can be completed in just a few steps. The process begins with obtaining a good understanding of the problem to be able to provide a detailed statement explaining the problem exactly. Next, the user must open an account with the GNOME project's GitLab system. Finally, the user must submit the statement of the problem, ideally, along with some information about the computer setup being used by the person experiencing the problem.

The explanation given below should be sufficient to file a report. For more detailed instructions, the main page of GNOME's GitLab can be found at `https://gitlab.gnome.org/GNOME` and instructions can be found at `https://wiki.gnome.org/Community/GettingInTouch/BugReportingGuidelines` .

# Defining the error

The most critical step is understanding the error as well as possible. This requires knowing clearly what was happening before the error occurred, what specifically caused the error to occur, what the error condition is and what happened as a consequence of the error.

The most helpful situation to enable the developers to find and correct the error is to come up with a sequence of steps that generate the error. If the error can be repeated, it can almost always be corrected. The most helpful error reports include a small recipe that can cause the error to occur.

# Opening an account

The first time a user uses Gitlab, they must create an account. This account is needed to allow users to be informed of the status of the bug as it is tracked by the system from submission to resolution. The only requirement for opening a Gitlab account is the possession of a valid email address through which the user can receive a password.

## Creating a new account

Users of Gitlab are automatically redirected to a login page, unless they have previously logged into the system and accepted a 'cookie' with which they identify themselves. The login page has a link called "Create a new account" which will direct users to the account creation page.

Alternatively, by clicking on this link, users can follow a shortcut directly to the account creation page.

Creating a new account is very simple. The account creation page has two fields. In the first, a valid email account must be given. The second asks for a name by which the user wishes to be known. After a user fills out these two fields, clicking on the button labeled "Create Account" will cause a new account to be created and an email sent to the address given in the email field. The email will contain the password used to identify this user.

## Logging into the account

After creating an account, users can visit the bug entry page for &gnum;. Here users are asked to login with their email address and password. After logging in, GitLab will present a page to add a bug report.

A user who accepts cookies from `gitlab.gnome.org` will only have to give a password the first time they visit GNOME's GitLab. During all future visits, GNOME will recognize the cookie and thereby identify the user.

# Filing a report

In order to file a report of a problem with &gnum;, a GitLab account is necessary. Please see the previous section, , for an explanation of how to open an account.

The &gnum; 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.

## 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 &gnum; page.

Alternatively, users can click on this link to access the &gnum; page in Gitlab.

If neither of those shortcuts work, the user must use a web browser to access the following location:

    https://gitlab.gnome.org/GNOME/gnumeric/-/issues/new

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 for an explanation of how to login to GitLab.

## 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.

    thanks,
    a user

## Product and Component

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

The Component describes the part of &gnum; 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 &gnum; are as follows.

### Components 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 &gnum;.
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 &gnum; 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.

## 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 &gnum; 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.

### Problem 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.

## The Version of Gnumeric and GNOME

The version field is used to indicate the version of &gnum; 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 &gnum; is being used with a GNOME desktop, the version of GNOME being used can be entered in the "Gnome Version" field.

## 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 &gnum; 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.

## 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.

## 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.

    https://gitlab.gnome.org/profile/notifications

## 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 &gnum;.

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 &gnum; page of GitLab with the common fields already filled out.