Technical Debt Program

Overview
The Technical Debt Program is being developed to help the Foundation and the broader community better manage MediaWiki technical debt. This article's purpose is to help document a process by which the Foundation and community can: For more information about Technical Debt in MediaWiki, please see the Technical Debt article.
 * avoid incurring more of it
 * manage it
 * reduce it

The Technical Debt program is being developed by the Code Health Group.

Removal (paying off debt)
Removal of technical debt is focused on the overall reduction of existing technical debt. Within the MediaWiki ecosystem, we have a large existing codebase with an undefined amount of technical debt. This existing technical debt may or may not be impacting our daily efforts. How do we find it and determine if it needs to be removed?

Patterns to look for are: Generally speaking, those that work on the code gain a pretty good understanding of those areas that are hard to work with. They may even have some ideas as to how to make it easier to work with.
 * An area of code that people avoid at all cost due to fear of breaking it or general lack of understanding.
 * An area of code that seems to break often.
 * An area of code that is developed and maintained by a single person (because they are the only one who understands it).

Once areas have been identified, what then? Prioritizing the work can be challenging and often results in the “low hanging fruit” approach. All things being equal, the LHF approach isn’t a bad one. When you have equally impactful areas that need attention, choose the easiest ones first. However, all too often, impact-fulness is not factored in when selecting the LHF. As a result, a bunch of work is done (tasks completed), and people feel good about the shorter list, but the actual impact is marginal.

For that reason, impact should be the primary criteria when prioritizing the removal of technical debt. For example, if there’s an area of code that is routinely modified vs an area of code that is changed only once every 3 years, the impact of removing the technical debt from the prior is probably more impactful. This is perhaps an overly-simple example, but it does demonstrate some of the factors to consider.

Once the areas are identified, the work at hand needs to be identified. To that end, sound design and implementation principles should be followed or one risks removing some technical debt while introducing different technical debt. For that reason, it’s important that all that contribute to MediaWiki employ sound software development principles. The Code Health Group, a cross organizational group responsible for defining these principles, is a good place to start.

In-Practice: All too often developers go into refactoring efforts with the expectation that nothing will break. However, the reality is, things WILL break. As with any other development, having adequate tests in place will help manage the breakage. Don’t be afraid to break stuff, expect it.

Avoidance (not incurring new debt)
Where removal focuses on the reduction of technical debt, avoidance is about minimizing the introduction of any additional technical debt. As noted previously, technical debt isn’t necessarily bad, provided it’s a conscious decision with well understood benefits and costs, and a plan to remove it at a later date.

Avoidance is made up of two distinct parts - knowing how to design and implement a debt-free system, and understanding when to incur technical debt and when not to.

Knowing how to design and implement a debt-free system is outside the scope of this post. Please see Code Health for more resources on that topic. That being said, example are: code complexity, coding standards, and test coverage.

Equally important is when to make the decision to incur technical debt and when not to. The following is a diagram of a decision tree to help make a good technical debt decision.

Key points from the diagram:
 * Don’t incur the tech debt if it takes longer to discuss and document it than to take the more desirable approach.
 * A lot of small shortcuts are difficult to document and track.  Over time, they will crush productivity.
 * Although discussing tech debt decisions with peers and your direct engineering manager may be enough for tactical short-term tech debt, longer-term strategic tech debt should also be discussed with the Product Manager and Tech Committee as the impact of the tech debt may be broader.