How to Use Issues in Arctos

The Issue Process: How to Make Arctos Work for You

• Improvements to Arctos can come from any Arctos user. Suggested improvements can include simple coding bug fixes, the addition/deletion of data fields or menu items, new forms/buttons/functions to streamline collection processes - anything that will help Arctos users better manage and access Arctos data/specimens/objects.

• Changes to Arctos are submitted, discussed, prioritized, and tracked to completion using Issues in GitHub. Once an Issue is created it will be reviewed by the Arctos Working Group.

• Issues that do not require a discussion (bug fixes or broken forms/functions) will be resolved by Arctos programmers.

• An Issue requiring discussion will be considered by the Arctos Workinig Group, the Issue author, and other interested users - Issues and discussions are open to all. The discussion of an Issue occurs within the comments of the Issue.

How to File an Issue

• You need to create a username and login to Github (see "How to Use GitHub for Arctos") to file an Issue.

• Use this link https://github.com/ArctosDB/arctos/issues/ to access Arctos Issues.

• Search existing Issues to be certain your Issue does not already exist. If a similar Issue already exists you can comment on it.

• If you want to create a new Issue, click the green "New Issue" button in the upper right of the Issues list. Enter a short but clear title, and a description of the Issue in the text box where it says "Leave a comment." Click "Submit new issue" to assign the new Issue a number. Be clear and verbose in explaining the need and intended goals; provide specific examples, screenshots, or anything else which might help us understand what you wish to accomplish.

Managing Issues

• Anyone can submit a new Issue or comment on an existing Issue, but that's about all that they can do.

• Owners of the ArctosDB organization can manage Issues, meaning that they can do one of several things:

• Assign an "Assignee" - When filing an issue, leave Assignee blank. It's fair game for everyone to ignore "assigned" issues.

• Assign a Milestone. Every Issue should be assigned a Milestone (see Guidance below).

• Assign a Label to an Issue (see Guidance below).

• Change the Status of an Issue. All resolved Issues should be marked as Closed.

Guidance on Assigning Milestones

• Needs Discussion: The path to implementation is unclear and requires discussion by involved parties, the Arctos Working Group, and/or the broader Arctos Group. If an Issue is important to you, you should participate in these discussions.

• Next Task: The development needed is well-defined and accepted; just needs code written. Everything under this Milestone should have a Priority label; please add one if necessary.

• Active Development: Code is being written. Use this as development begins; make sure an Assignee is listed.

• Wish List: Major development, or development requiring major funding.

• Wont Fix: We have chosen to close the Issue without action. Leave verbose comments when using this.

• Abandoned: Use this to close Issues that have been awaiting feedback for ~months.

Guidance on Assigning Labels

• Priority Labels

• Priority-Critical: Issue is causing major problems for multiple users; corrupting data, crashing servers, etc.

• Priority-High: Issue is actively preventing progress.

• Priority-Normal: Standard Issue

• Priority-Low: Needs fixed/implemented/discussed, eventually.

• Classification Labels

• Type-Form/Function: Front-end Issue that has to do with either an interface form or specific functionality of Arctos. These types of Issues may include: Bug - defective code (e.g., the "save" button does not save); Enhancement - a request for additional or improved functionality (e.g., an idea for improving efficiency); Performance - a request for tuning (e.g., a query times out).

• Type-Data/Database: Back-end Issue that refers either to specific data (e.g., data migration issue, code table spelling error) or the database itself (e.g., data table structure, security, etc.).

• Functional Labels

• There are different kinds of "Function-Thing" labels to help categorize Issues. For example, an Issue on how Arctos functions with regard to places or events (including georeferencing) should be assigned a "Function-Locality/Event/Georeferencing" Label.

Useful Filters

• "Active Development" Issues are those which we're working on right now. This should be assigned only by the person who intends to address the Issue.
• "Next Task" Issues are those which are ready for implementation. GitHub has no voting system, but please leave a comment to help us prioritize.
  • Critical
  • High
  • Normal
  • Low
• "Needs Discussion" Issues are those which sufficient information to proceed is not available. Please add a comment to the label as a means of discussion.
• WishList Issues are those which, at the time of last evaluation, we don't have resources to develop.
• Abandoned Issues are those which we did not receive enough information to proceed. Please re-open and comment!
• uncategorized Issues require a Milestone.