In every complex project, we use a lot of external dependencies and tooling. Of course, they have bugs.

Thanks to Github and the like, it is very easy to fork a project and track issues in libraries dependencies so that's not the scope of this question.
The tooling however, can me much more complex to inspect, debug, and submit. Let's restrict here to the Open Source tooling.

If the tool is only used for development and testing purposes, the priority for fixing these annoying bugs is quite low. That's why often, we don't even report the issue as soon as someone found a workaround.

This is bad. We should keep track of the tooling issues as it explain a lot about the life of the project and having them somewhere show everyone that we can fix it, and it will be some value in these fixes. But in the other hand we can't put these issues in the same bucket that the project because they are unrelated and will pollute our issue tracker.

Happiness of my team is one of my top priority, and I cry inside when I see them having to document complex rituals for random situations involving specific conditions met once a week or less.

How do you handle the issues related to your tooling ? How do you prioritize these bugs ?

I realize that my question is quite vague, but I hope it's clear anyway. I will be happy to improve it if you see some flows.

  • Could you explain how they will pollute your issue tracker? Can't you just record these at the lowest priority (indicating that they do not affect shipping code)? Does your bug tracking system permit you to tag them? Is your level of technical debt so low that you have a chance to get to these bugs? How do you prioritize bugs now?
    – MCW
    Jul 18, 2014 at 16:58
  • I currently use Kaban boards (Trello) linked with tech and support resources. It's a pretty flexible setup. I think the pollution will be as a constant noise with a bunch of long tasks with low business value. I want my team to clear happily the board during the week, this is not compatible in my mind with a list of long lasted task never filled, staying just next to the sprint. About our bug policy, we solve bugs before writing new code (point 5), so our technical debt is quite low. Jul 19, 2014 at 10:20

2 Answers 2


Tribal Knowledge is Normal

We should keep track of the tooling issues as it explain a lot about the life of the project and having them somewhere show everyone that we can fix it, and it will be some value in these fixes.

All projects accrue a certain amount of tribal knowledge during the typical project lifecycle. What you seem to be struggling with is how to properly capture that knowledge.

Don't Constrain Solutions by Tools at Hand

Some of your process difficulty may stem from the belief that all processes can fit into a single tool—in your case, that would be Trello. While it can be tempting to use a single tracking technique to track everything, this can sometimes be counterproductive. Don't be afraid to add additional trackers, knowledge repositories, or tools at need. The important thing is to ensure that everyone on the project knows where essential information is likely to be found.

Some Common Solutions

There are two obvious routes. For external tools, such as open source projects on GitHub, you don't have to patch the tool to contribute effectively. GitHub in particular generally supports repository-specific issues and wikis, and these are a good place to document problems and work-arounds even if you aren't able to provide a permanent solution. Non-GitHub projects have other mechanisms, of course, but contributing upstream is really the best long-term solution.

For internal tools, or for external projects that don't provide a way to contribute knowledge back to the community, I often find that a project-specific knowledge base or wiki is immensely useful. The tool used for knowledge capture isn't what's important here; what matters is that you are capturing your workflows and work-arounds in a central clearinghouse that is available to the entire project team.

Documentation and Automation

To ensure process efficiency and repeatability, tooling and infrastructure should always have a documented process for implementing components. This should be a living document, and if kept up to date will contain those bits of tribal knowledge that are currently going astray.

On software projects, this "living documentation" can often be in the form of provisioning or setup scripts. No one has to spend time reading the documentation as long as the project team takes the time to keep the scripts up to date. This is essentially a way of continually paying down technical debt, and should probably be a recurring task melded into your Definition of Done for each iteration (if you're agile), or be revisited at critical milestones or checkpoints if you're following a more traditional methodology.

  • Thanks for your detailed answer. We will change our CI and automation to be more descriptive, and apply your recommendations. Jul 22, 2014 at 10:43

Create the tickets in the bug tracker of the respective Open Source tooling

I could be wrong, but it sounds like you have a fond hope of fixing these bugs, but may not ever get around to assigning developers to fix them!

Instead please ask the team to spend the small amount of time it takes to create the tickets in the bug tracker of the respective Open Source tooling. Please add steps for reproducing, error messages, screenshots...and so on. If you have found work arounds, please add them as well.

This helps in the following ways:

  1. If you ever find the time, you can always go back to find these tickets and fix them.

  2. In the meantime, anyone else is able to fix them as well.

  3. And you won't be polluting your issue tracker.

  • Thanks for your answer. It's common sense but sometimes not so obvious to apply. As the other answer offer few more insights about "tribal knowledge" (something I wasn't aware of), I validate the other answer as valid, but yours is interesting nonetheless. Thanks you for your time sharing your insights. Jul 22, 2014 at 10:44

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.