šŸ“ Issue TrackingĀ¶

SummaryĀ¶

Issue tracking is a great tool to track pending work and improve the overall communication within a project. But similar to every other tool, it needs to be used with care.

ā€œA fool with a tool is still a foolā€
ā€“ Grady Booch

This guide will try to help you to get the best out of the issue tracking for you, your teammates and the project(s) you are working on, by answering the following questions:

  • When to create an issue?

  • What makes a good issue?

  • How to maintain an issue?

When to create an issue?Ā¶

Let me start by saying there is no perfect and one size fits all ruleset to decide this question, otherwise there would be some code doing that for us. The good thing though is, humans are great in dealing with fuzzy problems. Still most people want to have something to orient themselves. Asking more specific questions often helps in this situation.

The following question(s), helped us in the past, to get a better handle on this:

  • What is the cost/benefit ratio of creating an issue?

    • cost being mainly time and effort

    • benefit being the upsides we gain from having an issue

  • What is the signal to noise ratio?

    • signal being the actual code/change bringing some benefit/value to the project

    • noises being the overhead

  • Is the user (api or product) impacted by this change?

    • Is it an ā€œinternal improvementā€ quality of life and/or code quality

ExamplesĀ¶

Fixing a couple of typosĀ¶

You stumble upon a couple of typos in a Project.

Possible Action(s)Ā¶

  • You fix the typos without creating an issue

Suspicious amount of typosĀ¶

You stumble upon a various typos within a piece of documentation you are reading. Because of the vast amount of typos and the overall structure you expect the whole documentation to contain a substantial amount of typos.

Possible Action(s)Ā¶

  • If the documentation is not to big and you can make the time to fix the typos right away without creating an issue.

  • If the documentation is quite big, and fixing this e.g. would take you more than 1/2 a day you definitely should create an issue.

  • You are unsure how long it will take to address and check the documentation and you currently canā€™t spent time for detours create an issue.

What makes a good issueĀ¶

TL;DR: An good issue describes a piece of work, itā€™s context and itā€™s assumption in a way, any person capable of working on the project, can understand it, based on the information referenced and within the issue.

To begin with, we want to make sure you understand that creating good a issue is not a zero effort action. Various things like issue templates, can remove tedious boilerplate work, but still creating a good issue is some actual work. It is crucial to have well crafted issues, because bad issues do way more harm than good. So letā€™s take a step back and letā€™s think about why we need to have good issues, in order to better understand what actually makes a good issue.

Boiled down to itā€™s core issue tracking is just a list of pieces of work which are needed to be done. This list in turn, then can be used to plan, organize and track ā€œprogress/workā€.

Broken down to an individual issue, this means an issue should provide all relevant information about a ā€œsingleā€ piece/unit of work.

Even though the part what an issue is about is well understood, by most people, this is also where it goes wrong.

Why? Because we as humans tend to use and assume context implicitly. Assuming context implicitly already can be a problem when communicating with people we meet on a regular basis, but is a huge problem when you communicate with people which we meet rarely or even never.

This is somewhat obvious when you think about the fact that 60-70 % of human communication is non verbal communication. This most likely also part of the reason so many people use emojies, a picture says more than a 1000 words and therefore can help transport context more easily šŸ˜‰. But even those helpers arenā€™t perfect and it very often depends on the mood and the other persons perception (context) of you how they interpret a specific emoji you have sent.

To take on a more computer science specific example:

TL;DR: Context mattersĀ¶

Information

Context

Value

65

ASCII

ā€˜Aā€™

65

Hex

101

65

Decimal

65

As you may have realized by know our point being how information is understood and processed highly depends on the context.

To come back now to the topic of ā€œWhat makes a good issueā€, a major part of it is to make context and assumptions an explicit part of your information you are providing. Write the issue in such a way, that a person working on the project, now or in the future can precisely understand the task, the context and assumptions of it.

Attention

You may inclined to think, you gonna address this task anyway or it is just for ā€œyourā€ book keeping, but then this is nothing for the issue tracker rather something for your personal todo list. If you decide it is important enough for the issue tracker than treat it as such.

So what does this mean in more practical actionable terms?

  • Make your context explicit

    • Add links and references to spec you may already know

    • Add information e.g. from discussion, meetings, mails ā€¦

  • Make your assumptions explicit

    • Write them down also note e.g. if you are not sure if it is the right decision but what you have taken into account at the point in time when you wrote it down

  • Add SubTasks regarding ā€œstandardā€ processes which people may not necessarily know about

    • This can be simplified e.g. by providing issue templates

    • update documentation

    • update changelog

    • ā€¦

  • Make it easy to answer the following questions for the person working/reading the issue

    • Is this issue still relevant, or is it obsolete by now?

    • Are the assumptions still valid today?

    • Did they have more or less context than we have today?

    • Did I consider the assumptions and context of the one writing the issue?

Attention

More details on a specific issue type you will find in the corresponding subsection(s) of this guide.

How to maintain an issueĀ¶

As you already know an issue does not only keep track of what needs to be done, but also about itā€™s context (how, why, etc.). This context can be a quite dynamic though, especially for tasks which bare a larger amount of uncertainty (e.g. bugs). So a huge part of keeping an issue up to date, is keep updating itā€™s context. The following scenarios will try to give you an idea on how to update and maintain an issue in various scenarios.

TL;DRĀ¶

  • Keep the issue and itā€™s context up to date

    • Keep the status up to date [Backlog, In Progress, ā€¦]

    • Update tickets which are actively worked on regularly (at least every 2-3 days)

    • Try to communicate new information via comments (e.g. status updateā€™s)

    • Report important changes because of internal and external events

  • Comments

    • Respond to comments in a timely manner

    • Stay friendly and focused on the issue when responding to comments

ScenariosĀ¶

A developer picks up the issue from the backlog and starts working on itĀ¶

  • Assign the ticket to the developer working on it

  • Change the state of the issue to ā€œIn Progressā€

    Note

    Most issue tracking system already take care of this if you move it to the appropriate category in the issue(s) overview.

The Issue Receives a commentĀ¶

  • Make sure to reply to a comment in a timely manner

  • If it is the first contribution/comment of the contributor on this issue, show appreciation for the contribution.

    • If the comment canā€™t be addressed right away, at least acknowledge the comment and communicate some timeframe

  • Make sure the comment can be understood in the context of the issue

    • If needed ask for clarification

    • If needed ask follow up questions

  • Be clear in your response(s)

    • Make sure relevance, importance, course of action and timeframe are communicated if necessary

The Developer stopā€™s/postpones working on the issue, e.g. due to re prioritizationĀ¶

  • Remove assignee on the ticket

  • Change the state of the issue to ā€œBacklogā€

    Note

    Most issue tracking system already take care of this if you move it to the appropriate category in the issue(s) overview.

  • Make sure all current context information is updated or added as status comment to the issue

  • Add information about why working on the issue have been postponed/stopped (e.g. blocked)

    • Except if this would disclose information to the wrong audience

  • Communicate when work on the issue will be picked up again

    • Communicating that it is unclear when the work will be continued, is also fine

Stalled issue (e.g. root cause of bug is hard to find)Ā¶

Note

Very rarely the issue (work) is really stalled, often it just feels like this. When you canā€™t report on explicitly achieved task(s), provide context information about your work (journey). This can help you and others to pickup on it latter or at least it help to understand the current state more clearly.

  • Regularly post a status update on the issue (every 2-3 days)

    • What issues/problems already have been ruled out and why?

    • What is the current strategy to find the culprit?

    • What is the current strategy to resolve roadblocks?

    • What are the current assumptions and hunches?

    • Are there any further leads to be investigated in the future?

    • Describe the current roadblocks

    • Report sub partial successes

    • Add scriptā€™s and context information which helps to reproduce and/or trigger the bug

Example: Status Update on Bug Issue

# Status Update
Further investigation's have shown that the basic SQLA test suite mostly is intact after the upgrade to `1.4` (14 failures), when run in "isolation". Various exasol specific test suites:

   * test/test_get_metadata_functions.py
   * test/test_large_metadata.py
   * test/test_regression.py (TranslateMap)

seem to have negative side effects which cause 100+ tests to  :boom: fail/crash, if run after those test suites.
This further strengthens the case for the **assumptions** mentioned in the previous update:

   * Setup/Teardown mechanic of `testing.fixtures.TablesTest` has changed
   * Setup/Teardown mechanic fails due to leftovers in tests DB

Also, this narrows down the potential root cause(s).

## Remark(s)
Common to all those test suites to be that they add/remove schemas.
For `test/test_regression.py` it have been proven that the schema manipulating test (`TranslateMap`) causes some negative side effect on following test suits.

## Notes & Ideas (from discussion with @tkilias )
* Is schema inference still working correctly?
* Does the "disabled" caching cause side effects?
* Do implicit schema open and closes affect the current schema for follow up tests?

## Next Steps
* Analyze effects of implicit open/close of schema(s)
* A more in depth analysis regarding side effects and cleanup of the mentioned test suites will be done

To see the example update in itā€™s full context look here.