I've never thought of Technical-Debt as mostly "design" issues but rather missing unit tests, duplicated code, using deprecated API or incomplete API.

In T129651#2111855, @Aklapper wrote:

I've never thought of Technical-Debt as mostly "design" issues but rather missing unit tests, duplicated code, using deprecated API or incomplete API.

So can something "missing unit tests, duplicated code, using deprecated API or incomplete API" still be considered "well designed"?

Seems to tie in pretty well with T119032: WikiDev 16 working area: Software engineering

@Aklapper "technical dept" also applies to design issues, such as relying on global state, or mixing concerns in a single huge class.

Something can be missing unit tests and be well-designed; if you take a well-designed component and rip off all the tests, the design is not changed.

More pragmatically, I would imagine Architecture to be used to groom large architecture tasks for ArchCom/cross-team efforts while Technical-Debt is mostly used by teams to label their own backlogs; so the first should be used for big issues which require an unusual level of expertise or need consensus, and the second for simpler issues which mostly just need to be done.

In T129651#2136860, @Tgr wrote:

Something can be missing unit tests and be well-designed; if you take a well-designed component and rip off all the tests, the design is not changed.

That's sorta like saying you can take a well-designed car, then remove all of the diagnostic gear, and you still have a "well-designed car".

As you imply ("More pragmatically..."), we don't talk about ripping out well-designed unit tests. We frequently discuss many parts of the code don't have tests. Very frequently, we lament those areas aren't well-designed enough to make test writing practical. The tests need to be there to ensure we get early warning from design mistakes, so that we don't end up with more technical debt because of new code that breaks untested contracts.

More pragmatically, I would imagine Architecture to be used to groom large architecture tasks for ArchCom/cross-team efforts while Technical-Debt is mostly used by teams to label their own backlogs; so the first should be used for big issues which require an unusual level of expertise or need consensus, and the second for simpler issues which mostly just need to be done.

What is the value in rigidly compartmentalizing these? This seems like two ends of a continuous spectrum with no clear separation point (e.g. a central argument for T384 is to remove technical debt and enable easier and more effective testing). It's important that people who care deeply about either end of the spectrum consider solutions with a view of the entire spectrum.

I'm not (yet) suggesting that we merge these tags. Let's figure out how to have an efficient path for escalating large-scale Technical-Debt issues from small-scale venues.

I think these tags can live independently. I'd recommend against making Architecture a generic yellow label as that seems redundant with Technical-Debt, and TechCom-RFC (and #RFC). But as its own project component (like it is now) it doesn't seem to overlap with Technical-Debt.

We already have TechCom-RFC for architecture-level changes. (And TechCom for its internal process.)

I see Technical-Debt primarily used for identifying code smell. Relatively small issues, or larger tasks that are otherwise uncontroversial. Typical technical-debt tasks are "Convert X to use Y instead of deprecated Z". (e.g. "Convert CategoryTree from AjaxDispatch to ApiModule", or "Convert legacy X to use ResourceLoader", or "Make X be RequestContext-aware".)

Tasks about implementing a foundational system itself (e.g. ResourceLoader, API, RequestContext) are not covered by the process used for technical-debt. Instead, such tasks are RFC material that require wider discussion. (If a new system replaces an area currently in debt, one could add the Technical-Debt tag to the RFC.)

Technical-Debt is used like Wikimedia-production-error. It's an easy grab bag for helping out somewhere.

In T129651#2147031, @Krinkle wrote:

I think these tags can live independently. I'd recommend against making Architecture a generic yellow label as that seems redundant with Technical-Debt, and TechCom-RFC (and #RFC). But as its own project component (like it is now) it doesn't seem to overlap with Technical-Debt.

We already have TechCom-RFC for architecture-level changes. (And TechCom for its internal process.)

I see Technical-Debt primarily used for identifying code smell. Relatively small issues, or larger tasks that are otherwise uncontroversial. Typical technical-debt tasks are "Convert X to use Y instead of deprecated Z". (e.g. "Convert CategoryTree from AjaxDispatch to ApiModule", or "Convert legacy X to use ResourceLoader", or "Make X be RequestContext-aware".)

Tasks about implementing a foundational system itself (e.g. ResourceLoader, API, RequestContext) are not covered by the process used for technical-debt. Instead, such tasks are RFC material that require wider discussion. (If a new system replaces an area currently in debt, one could add the Technical-Debt tag to the RFC.)

Technical-Debt is used like Wikimedia-production-error. It's an easy grab bag for helping out somewhere.

Ok, that makes sense. Thank you! So, let me see if I can restate this accurately (for something to cut-and-paste around):

(robla's draft)
Like all mature software, Wikimedia software is filled with design decisions may have made sense when they were introduced, but don't make sense today. We use these two tags to address these:

• Technical-Debt - for tasks that don't require a lot of coordination to correct, and can be completed by a single person or a well-organized team without permission or advice from others.
• Architecture - larger tasks with possible ripple effects that may impact other developers or teams ability to do their work, may create a lot of work for someone else, and/or may require significant investment to effect. Architecture tasks should frequently get advice from the larger Wikimedia developer community through use of TechCom-RFC.

These two tags have a lot of overlap, and the border is not well defined. It's going to be important for us to figure out when we cross the threshold between "annoying thing I should just fix myself" and "larger issue we should come up with a thoughtful solution for".

Does that wording make sense?

In T129651#2159375, @RobLa-WMF wrote:

It's going to be important for us to figure out when we cross the threshold between "annoying thing I should just fix myself" and "larger issue we should come up with a thoughtful solution for".

@Bawolff's patch (rMW42e433f14f4b) removing $wgWellFormedXml (and his email to wikitech-l) seem to describe something that lives in this grey area. Is what Brian did with his email the best practice that we want others to emulate in similar circumstances? (genuine question; I think his email is great and probably does represent current best practice, but I don't know when and how to ask others to "do what Brian did")

I'm assuming silence is assent on my proposed wording in T129651#2159375

In T129651#2257473, @RobLa-WMF wrote:

In T129651#2159375, @RobLa-WMF wrote:

It's going to be important for us to figure out when we cross the threshold between "annoying thing I should just fix myself" and "larger issue we should come up with a thoughtful solution for".

@Bawolff's patch (rMW42e433f14f4b) removing $wgWellFormedXml (and his email to wikitech-l) seem to describe something that lives in this grey area. Is what Brian did with his email the best practice that we want others to emulate in similar circumstances? (genuine question; I think his email is great and probably does represent current best practice, but I don't know when and how to ask others to "do what Brian did")

I'm assuming silence is assent on my proposed wording in T129651#2159375

Fwiw, i was going back and forth over if that should be an rfc, but it seemed too small. Im happy to hear you think it was a good choice of action.

In T129651#2257788, @Bawolff wrote:

Fwiw, i was going back and forth over if that should be an rfc, but it seemed too small. Im happy to hear you think it was a good choice of action.

Thanks for asking. I think you made a reasonable choice. TechCom-RFC's have a lore around them for being only for "large" things.

I would like for ArchCom to consider some "small" things too, and get some practice as moving some things through the process very quickly (e.g. not insisting on an IRC meeting for it). I believe that an TechCom-RFC is really much more about answering the questions "did I get suitable advice from the wikitech-l community?" and "did I ask all of the right people?". We have the "last call" part of the process now where ArchCom can more comfortably put something into last call without having an IRC meeting, as we did with T129435.

The "large" vs "small" consideration is much less about lines of code or number of modules touched, and more about:

1. The risk of the change (e.g. security, stability, performance, compatibility)
2. The danger of introducing a mistake that's difficult to reverse

One thing I would have preferred about an RFC for this is to have a Phab task for discussion of the change in question. This change isn't substantial enough to require a corresponding mediawiki.org page. I do think that the risk on 1 and 2 may be large enough to warrant a wide discussion.

All that said, I think you made a respectable choice. Your email to wikitech-l is clear enough that people who keep track of the list can have confidence in your consultation.

On the subject of the Architecture vs Technical-Debt distinction, this strikes me as something I've always thought of as "technical debt", but doesn't meet the @Krinkle's definition of "technical debt" in T129651#2147031.

I'm going to continue a conversation that @Krinkle started on T54807. That issue is a tracking issue for the various legacy preferences we have hanging around in MediaWiki core. Krinkle added the TechCom-RFC tag to that one, but then decided to remove it because we all got confused. He clarified in T54807#2276977. The portion of the conversation worth continuing here:

In T54807#2276977, @Krinkle wrote:

The RFC left here could be to discuss how we want to identify legacy preferences. To establish consensus about a policy detailing what criteria to apply and how to decide when to remove a preference. So far this doesn't seem very controversial though. We've successfully removed such legacy preferences through regular discussion and code review without the overhead of an RFC to establish a formal policy.

This wasn't originally marked as RFC (I did that last month as part of the split, I've undone that edit and restored this as a tracking trask).

Is this a case where organizing our work around technical debt cleanup would be useful?

(Krinkle described my understanding extremely well in T129651#2147031 - thanks!)

4⅔ months later: What's left to sort out / do in this task?
Has someone found a reply to

Is this a case where organizing our work around technical debt cleanup would be useful?

?

Thanks for the ping on this! I think this topic relates to all this:
https://www.mediawiki.org/wiki/Wikimedia_Developer_Summit/2017/How_to_manage_our_technical_debt

I'd like to resolve this task at Wikimedia-Developer-Summit (2017)

In T129651#2681240, @RobLa-WMF wrote:

I'd like to resolve this task at Wikimedia-Developer-Summit (2017)

Does anyone else plan to drive this topic at the summit?

TechCom decided today to archive this task. The Architecture workboard was originally created for an Architecture team, and later re-purposed as generic tag for tasks that propose changes that some believe are major in some way. This workboard, however, has never been part of TechCom's process and went mostly unnoticed. As such, it better reflects our current practices to remove this workboard and archive the tag.

Any task that requires input from TechCom should be tagged with TechCom-RFC (if it should be an RFC), or with TechCom (if it requires our input without being an RFC). We don't see any further need for the Architecture tag.