Managing issues that pop up during the software development cycle is a common practice. You’ll always have new enhancements to implement, bugs to fix, and maintenance tasks to follow up on. Sadly, there is no industry standard, or best practices, on how to go about managing these issues but there should be.
One way is to think in terms of present and past tense which provides a nice synergy with the corresponding Git commits that make up your implementation to complete the issue. Example:
| Present (issue) | Past (commit) |
|---|---|
Add |
Added |
Update |
Updated |
Fix |
Fixed |
Remove |
Removed |
Refactor |
Refactored |
There’s a nice simplicity to the above where present tense is used to describe what is desired while past tense represents the corresponding completed work. For example, let’s say we want to add documentation to the project. We’d record the issue as follows:
# Add project documentation ## Why Necessary explain what this project is about, why it's important, and how to make use of our features. ## How - Document requirements. - Document the setup process. - Document how to use our API endpoints. - Add links for license, code of conduct, and versions. ## Notes Would be nice to have this done by end of week.
Notice the subject, Add project documentation, is written in present tense. This is a request for action that hasn’t been completed yet. The body of the issue details why the issue is important, how to implement, and optional notes so anyone can pick up and complete the issue. The corresponding Git commit (or commits) would be:
Added project documentation Necessary explain what this project is, why it's important, and how to use it. Issue: 1 Milestone: minor
Notice the subject, Added project documentation, is written in past tense and is the corresponding response to the issue. Even better, the commit adheres to good Git Commit Anatomy in terms of what the change was and why it’s important while making good use of Git Trailers to link back to the issue (assuming the ID is 1) so all of this information can be used to automatically generate the release notes and corresponding versions for your Milestones.
Let’s break this down further by exploring what an issue is comprised of.
Subject
Your issue’s subject is one of the most important aspects of writing a good issue because you need to accomplish the following:
-
Clearly explain what the problem is.
-
Write for humans, not robots.
-
Use the minimum amount of information that makes your subject unique and searchable for others to discover and also learn from.
Your subject is also made of two critical components: <prefix> <body>. These are so important that they are broken down into two sections for further explanation.
Prefix
Your subject prefix is always a verb. There are five in total and each should correspond with your Git Commit Anatomy. There can be more but the following five tend to be the most common.
Add
Use to request a new enhancement. This is always meant for adding something new that currently doesn’t exist.
Update
Use to update an existing feature, behavior, etc.
Fix
Use to report a bug by explaining what the problem is and expected behavior should be.
Remove
Use to remove functionality that is no longer necessary. This can be dead code, a feature your customers no longer want, tooling/infrastructure no longer needed, and so forth.
Refactor
Use to refactor existing code by simplifying, moving to a more logical namespace, cleaning up the internals of your implementation without effecting the public API, and so forth.
Body
The subject body of your issue is what follows after the subject prefix. You want your body to be short and sweet with an emphasis on human readability. This means no code snippets, class names, or syntax of any kind because that is meant for the body of your issue, not your subject. The subject only needs to briefly explain what the problem is. You also don’t need long sentences or multiple sentences for this. If your subject wraps multiple lines then that is a clear indication you haven’t been able to summarize what the problem is. Here’s several examples of what good subject bodies look like:
-
Add binary build for the Windows operating system
-
Fix database dead lock with background image processing
-
Refactor style sheets to use functions for improved reuse
-
Update documentation to use demo instead of stage server
-
Remove the Bifurcate gem since maintenance ends in 2025
As you can see, each of the above example subject bodies support the prefixes by explaining what is needed without being overly verbose, using code snippets, or special punctuation. Each is clean, to the point, quick to search for, and written for fellow humans.
Template
Your issue template doesn’t have to be complex and can be configured as a repository template (preferred), generated by Rubysmith when building new Ruby projects, or generated as an Alfred Snippet (handy when a project has no issue template at all).
## Why <!-- Required. Describe, briefly, why this issue is important. --> ## How <!-- Optional. List exact steps to implement or reproduce behavior. Screen shots/casts are welcome! --> ## Notes <!-- Optional. Provide additional details like operating system, software version(s), stack dump, logs, or anything else that would be helpful. -->
The above uses Markdown syntax with code comments that are only visible within the template which clearly indicate which are required and what is optional.
The why of an issue is always the most important. Definitely appreciative of folks that can detail how to accomplish the task along any supplemental notes that might be of relevance.
Searches
When you adhere to the above, the ability to quickly search for different kinds of issues is vastly improved because there is a system and organization around your issues without adding a ton of labels (you can but this saves you a few steps).
Questions
You’ll notice, so far, there’s been no mention of dealing with questions. The reason is simple: questions are not issues. Use a forum and/or group chat to manage questions.
Avoidances
With the all of the above in mind, there are several aspects of writing good software issues that should be avoided. They are:
-
Avoid using prefixes, suffixes, or any kind of metadata that looks like this: "[BUG]", "FIX:", "#bug", etc. Write for humans, not machines. Keep metadata in your Git Trailers.
-
Avoid replacing the project’s issue template with your own. This is not only rude, but can get your deprioritized, banned, or fired entirely. Respect the wishes of the maintainers and you’ll get much further.
-
Avoid using incomplete sentences, no punctuation (or improper punctuation). Always write as if you were composing a letter with details, steps to recreate, code snippets, stack dumps, or anything that will help the project maintainers get to the bottom of your issue faster.
Hiring
There is an additional benefit to writing issues and commit messages: recognizing talent. As shown above, minimal ceremony is asked of the person submitting the issue but you’d be surprised — especially in open source — how often people will end up doing the weirdest things:
-
Ignore your project’s issue template entirely.
-
Fail to use a proper subject with the correct verb (tense).
-
Fail to explain the why and how of things.
-
Fail to use proper sentences, punctuation, bullet points, etc.
-
Fail to use proper ASCII Doc or Markdown syntax to improve readability (especially important for code blocks with syntax highlighting).
-
Fail to use the HTML Details element when code snippets or logs are verbose.
-
Not deleting the optional sections which look silly when left empty.
-
Adding new sections which make no sense or are irrelevant.
Due to the power of Personal Knowledge Management (PKM) systems, it’s simple to mark these individuals as no hires (not saying they can’t redeem themselves but the process becomes harder). First impressions are everything especially when interacting with someone for the first time, so ensure you always put your best foot forward because making a meaningful contribution lifts up the community and makes everyone better.
Good writers and thinkers are hard to find. They are a treasure when you find them!
Conclusion
With only a bit of effort, your issues can be organized, to the point, and (hopefully) quick to address. Enjoy and may you remain at Inbox Zero!