title: How we organize GitHub issues: A simple styleguide for tagging
url: https://robinpowered.com/blog/best-practice-system-for-organizing-and-tagging-github-issues/
hash_url: 986d37a75df767708b9e348e71b07345

<p>For people who make software, the internet has no shortage of best practice for workflow organization like <a href="https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow/" title="Git Flow explained" target="_blank">Git Flow</a>, <a href="http://semver.org/" title="Semantic Versioning" target="_blank">release versioning</a>, etc. When you get to the topic of issue management, the reading material plummets.</p>
<p>At Robin, <a href="https://guides.github.com/features/issues/" title="Issues in Github" target="_blank">GitHub issues</a> are the core of just about every action the team takes. Over the past year, we’ve worked out an internal tagging system that keeps engineering and product efforts organized across repositories on Github. We’re sharing the current iteration (and it will keep changing) in case your team is looking for some workflow inspiration.</p>
<h2>Styleguide for issue tagging</h2>
<p><img class="aligncenter" src="//static.robinpowered.com/blog/images/github-tagging-style/robin-github-issue-tag-system.png" alt="Robin's Github issue tagging styleguide"/></p>
<hr/>
<h2>Label Groups</h2>
<p>We group labels by color, according to broad themes. Labels are consistent across repositories, except for a few language specific topics. This makes switching between projects easy, since you don’t need domain expertise in order to write an issue. <strong>New team members can learn the system once, and use it everywhere.</strong></p>
<h3 class="issue-tag i-lightblue">Platform</h3>
<p>If the repository covers multiple parts, this is how we designate where the issue lives. (i.e. iOS and Android for cross-platform tablet app).</p>
<h3 class="issue-tag i-red">Problems</h3>
<p>Issues that make the product feel broken. High priority, especially if its present in production.</p>
<h3 class="issue-tag i-tan">Mindless</h3>
<p>Converting measurements, reorganizing folder structure, and other necessary (but less impactful) tasks.</p>
<h3 class="issue-tag i-orange">Experience</h3>
<p>Affect user’s comprehension, or overall enjoyment of the product. These can be both opportunities and “UX bugs”.</p>
<h3 class="issue-tag i-salmon">Environment</h3>
<p>Server environment. With good QA, you’ll identify issues on test and staging deployments.</p>
<h3 class="issue-tag i-purple">Feedback</h3>
<p>Requires further conversation to figure out the action steps. Most feature ideas start here.</p>
<h3 class="issue-tag i-blue">Improvements</h3>
<p>Iterations on existing features or infrastructure. Generally these update speed, or improve the quality of results. Adding a new “Owner” field to an existing “Calendar” model in the API, for example.</p>
<h3 class="issue-tag i-green">Additions</h3>
<p>Brand new functionality. New pages, workflows, endpoints, etc.</p>
<h3 class="issue-tag i-yellow">Pending</h3>
<p>Taking action, but need a few things to happen first. A feature that needs dependencies merged, or a bug that needs further data.</p>
<h3 class="issue-tag i-gray">Inactive</h3>
<p>No action needed or possible. The issue is either fixed, addressed better by other issues, or just out of product scope.</p>
<p>See a <a href="https://github.com/robinpowered/swolebot/labels" title="Swolebot">version of this in action</a> on one of our public repos.</p>
