How To Github: Create and Manage Github Issues for Arctos

Github Documentation

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.
• If your issue isn’t quickly resolved, please add it to the agenda of a Working Group (or other) meeting, then plan to attend, explain, and advocate as necessary to find a resolution.
• Issues which seem to be abandoned or are not moving towards resolution may be closed; please reopen with clarifying comments (or file a new Issue, decluttering is often useful) with plans to follow it through if the subject is still of interest.

How to Create an Issue

• You need to create a username and password to log into Github (see “How to Use GitHub for Arctos”) before you can file an Issue.
• Use this link https://github.com/ArctosDB/arctos/issues/ to access Arctos Issues.
• Search for existing Issues to be certain your Issue does not already exist. If a similar Issue already exists, please “adopt” it instead of filing a duplicate. (But, please do not change the fundamental nature of a partially-related Issue. If in doubt, open a potential duplicate.)
• 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.

Pro Tips

Use these pointers to streamline getting the solution you need.

• Tell us your overall goals or functional requirements. We can help only if we understand what you’re trying to accomplish in sufficient detail. This will often involve an explanation of why the goal is important - “we want to record _data_ because researchers need it for _purpose_.”
• Tell us what you hope to accomplish, not (only) how you hope to do so. We will get to how, but beginning the conversation with something like a Product requirements document will generally lead to more robust solutions and avoid target fixation.
• Include enough detail that someone with a solution to the problem - even a very unexpected one - might recognize the situation and offer help.
• Include enough detail that someone with a similar problem - even if they might not describe it in the same way - could recognize the solution being offered.
• Include enough information for us to fully understand and replicate the problem or request. This includes but is not limited to
  • Data as uploaded (ZIPped to attach)
  • URLs
  • Specific sequence of clicks to get to a point of interest
  • Text (not images!) of error messages (particularly the ErrorID - a UUID like 795B1D17-0461-4A03-B6DC1314448ED77F)
  • Screenshots
  • Arctos usernames of involved persons
• Make sure you’re in the right place. Most Issues should be filed in the “Arctos” repository, https://github.com/ArctosDB/arctos/issues.

Edit this Documentation

If you see something that needs to be edited in this document, you can create an issue using the link under the search widget at the top left side of this page, or you can edit directly here.