---
# System prepended metadata

title: Dealing with issues
tags: [qhub, guide, issues]

---

# Dealing with issues
###### tags: `issues` `guide` `qhub`

---

Every week a new collaborator for the development team will be in charge of community/issues handling...

## Issue handling model

- Fill in issue details: Identify the type of issue, set the appropriate label and assign a specific collaborator to work on it...
- You can set milestones for specific issues(?)
- Add comments: Every issue should receive at least a generic answer, to not let the user alone or feel that the project is abandoned
- If you are the signed collaborator responsible for the issue, we need a policy to detect when the conversation was solved or not. To best close and maintain the issues
    
    
## What do we expect users to do?
When you want to ask a question, keep followings:
- Read the docs carefully
- If the use is a client, maybe use another channel to ask a question or request a feature
- Write complete information as soon as possible: reproducible code, OS, version, full stack trace, etc…

There is a very interesting blog post about issue management in the ZenHub Blog that addresses very interesting topics
- https://blog.zenhub.com/best-practices-for-github-issues/

### Label definitions

- We should start reviewing if all the current labels are really necessary...

    - Some of the most used ones:
        - client-funded
        - Priority levels: low, high and critical
        - Stale (Automatic)
        - Status: there are a bunch, how to best use them?
        - type: we could possibly auto address those by using checklists in the issue templates...
            - authentication, backup, bug, community, conda-store, documentation
            - duplicate
                -  with the new weekly review we just need to close it, I don't think we need a label for it
            -  enhancement, epic, good first issue, groom
            -  hacktoberfest-accepted
                -  we could use a milestone for those?
            -  maintenance, monitoring
            -  need-help
                -  this should be used for pair programming?
            - no code required, on hold, platform, question, roadmap, stability, tech-discussion, test, theming, usability

## Initial thoughts for a step-by-step guide

- How to best triage our issues?
    - Defining new issue templates or enhancing the available ones. 
        - Should we redirect support discussions to somewhere else? If they are clients, slack?
        - Do you want to request a feature or report a bug?
        - Maybe a checklist (template)?
            -  bug report
            -  feature request
            -  support request 
            -  Other
        - The very first part of the issue should be a consistent brief of the problem, too much text might be a problem...
        - provide the necessary information, environment, bug description, etc. following the template.

    - Assign relevant labels, and someone from the development team...
    - @mention people who are probably related to it so they can take a look at it, or related issues (close duplicates?)

- Issue replies
    - Defining Some stock replies for common issues or discussions?
        - Is it a personal request?
        - Feature requests... How to handle it?
        - If the problem is related to someone not reading the docs... How to handle it?
        - Client issues? Defining a candy answer and a priory tag or milestone?
        - Documentation related issues?
        - ...


## Other Ideas

- Monthly discussion for new feature requests?


## Definitely want to keep

- needs discussion :: indicates an issue that is blocked that requires discussion (e.g. how to, when to, if to implement, etc.)
- documentation
- good first issue
- client funded
- feature request
- bug
- icebox :: implies not prioritied and in icebox, moved into icebox

## When to close an issue
- Issue is irrelevant to QHub
- Question/bug is answered/resolved
Stop using:
 - enhancement (rename)

