Revision as of 13:18, 21 May 2015

Main Page > Resources > Resources/Issue tracker

Artefactual uses Redmine project management software to track bugs and issues in AtoM. You can find our Redmine instance at https://projects.artefactual.com

Useful links

• AtoM in Redmine - homepage
• AtoM issues list
• AtoM Redmine Roadmap

We're currently in the process of cleaning up legacy issues from our issue list, but as we progress with this work, this is what you can expect to see:

• An issue can refer to a feature, a bug, or a task. Features are enhancements or new functionality that did not previously exist. Bugs are reports of existing functionality that does not work as expected, or problems with the application. Tasks, used more rarely, are usually reminders to developers or analysts working on a release to perform some task necessary for the related release.
• An issue is given a Target version (e.g. Release 2.1, Release 2.3) only if we are certain it will be included in an upcoming release. Bugs that are reported but not sponsored for development or fixed by Artefactual or via community pull request will be left without a Target version until they have been addressed, and can be associated with a specific release.
• Bug reports should be given a Tested version, so that we know which version of the application was used to reproduce the issue, and we can assess if a bug remains relevant to future releases over time.
• Unsponsored feature requests can be found in the AtoM Wishlist project. When a wishlist ticket is sponsored for development or submitted via pull request by a community developer, the ticket will be copied into the public AtoM project.

Register for an account

You can register for an account in Redmine at: https://projects.artefactual.com/account/register

Search for a bug or issue

Anyone can search Redmine for an existing issue or bug. Visit https://projects.artefactual.com and enter your search keywords.

You can also browse AtoM issues here: https://projects.artefactual.com/projects/atom/issues

Note that issues or bugs related to client-specific development will not appear if you are not logged in, and further if your account is not associated with that project.

Create a new bug or issue

Below are some guidelines on using the fields you will find in Redmine when you open a new AtoM issue ticket. Before doing so, however, please consider what you need to report, and what the most effective way of doing so will be! Here are some external resources to consider, that offer general guidance on bug reporting:

Eric Raymond and Rick Moen's How To Ask Questions The Smart Way and Simon Tatham's How to Report Bugs Effectively are excellent descriptions of how to write a bug report. The Mozilla Foundation's bug writing guidelines may also be useful.

To create a new bug or issue, navigate to the AtoM project by clicking on "Jump to a project" and then "AtoM". Click on "New Issue" and fill in the required fields as outlined below:

Tracker

Choose "Bug" for an issue with an existing feature, or "Feature" to suggest a new functionality to AtoM.

Subject

Provide a brief description of the bug or feature you are requesting. Remember, this will be the title of the issue, and the way that other users, whey they search for bugs, will find yours! To help us avoid duplication, try to make your title clear and descriptive. Using language from our User Manual glossary can help (see our AtoM documentation - the User manual for the latest release will have an extensive glossary available).

Description

Helpful information to include in the Description field are the steps to reproduce the bug or behaviour you are experiencing. For us to be able to best diagnose any bug reported, other developers will need to be able to reproduce it. Our preferred method for bug reporting uses a 3-part description, as follows:

To reproduce:

Outline the exact steps required for someone else to recreate your bug. You can assume the reader will be familiar with the application, but you should still ensure your instructions to reproduce are clear and detailed. For example:

1. Log in as an administrative user 2. Navigate to Browse > Archival descriptions 3. Click on the "Level of description" facet for Item

Error encountered:

What happens when you perform the steps described above? Include any details you think are relevant. If you think it will be helpful, you can take a screenshot of what you are seeing and attach it to the issue ticket.

Example:

Results list displays items, series, and files. See attached screenshot.

Expected result:

Describe to us what *should* have happened at the end of the initial steps to reproduce; what you would expect to happen if the application was responding properly. For example:

Archival description browse list results should be limited only to records whose level of description is "Item."

Notes

Not always necessary, but if there are other details that will help us, please share! What have you already tried to troubleshoot the problem? What browser were you using, and did you try to repeat the error on a different browser (or after clearing your browser cache)? Were you or your system administrator able to reproduce the problem while in Debug mode? If so, please save the stack trace (e.g. error message you see) and attach it to the issue! Is there anything particular about your installation that might be causing or affecting the bug, that we should know about? Have you added custom code to your application that is not included in a public release?

Anything that might help us better diagnose the problem - let us know.

Status

Leave as New.

Priority

Please leave at Medium. Artefactual staff will triage the bug or feature as appropriate.

Tested version

Please select the version of AtoM that you reproduced the bug in. If you are unsure, you can always check your installation by navigating to Admin > Settings - the first field on the settings page will tell you which version you are running. Select the corresponding version from the list.

Other fields

Please leave blank and Artefactual staff will update as appropriate.