Learning patterns/Developing intercompatible components within a complex and often inconsistent system

A learning pattern forSoftware development

Learning Pattern Library

Developing intercompatible components within a complex and often inconsistent system

problemMediaWiki (and other such systems) comprise of many components often attempting to use inconsistent interfaces. This has very different results depending on which are put together.

solutionInvestigate. Clean things up. Update older components to make them properly work with your own.

creator• Isarra

created on16:23, 31 August 2019 (UTC)

status:DRAFT

What problem does this solve?

When developing with mature software, especially open source software of scale with many diverse users and contributors as MediaWiki is, things can get very inconsistent over time, both internally and in terms of user-facing interfaces. Specific expectations often exist, but may not be documented, or followed. Many components will predate the addition of the correct interfaces to implement what they want to do, and will employ bizarre workarounds which no longer make sense.

Working within such an environment to create or maintain components that do not trip up users due to conflicts and inconsistencies, while also keeping these components easily maintainable over time such that the workload is lessened the more mature they become, rather than increased, is a very hard problem in software development.

What is the solution?

Take the time to figure things out. Learn your environment. Work on improving not just your own components, but the components around them so that they all work better together. Standardise. Establish wider needs so that they can be met effectively for all stakeholders, and people don't need to run into the same problems later.

Do not solely focus on a single product, or stack of products. The environment you work in is much wider than the products you 'own', and if you want any of them to last, they need to be maintainable, and worth maintaining. That which they depend on needs to be worth maintaining. An interface used consistently by twenty different things is much more likely to be maintained than one used by two.

Things to consider

• Avoid scope creep. Many things will simply be out of scope. You will need to make determinations as to whether or not it's worth bringing compatibility fixes against other products into scope based on how much trouble it will save you in the long run.
• You need to become familiar with the appropriate interfaces in order to fix things. You will need to be able to keep up with changes upstream as things need to be updated. Often nobody is maintaining anything. All of this can prove to be considerable overhead, and often a very steep learning curve even for the best developers. It will take time.
• You may need to be able to put things into very different terms in order to explain things to management, or even to other development teams with differing priorities. Consider those priorities. Figure out how what you're doing fits those priorities. It should fit them, though perhaps in different ways than it fits your own. If it doesn't, this could mean that their priorities are very wrong to begin with, or just as easily that it's you who are headed in the wrong direction and may need to reconsider your own priorities.

When to use

• Any MediaWiki development, such as for resolving compatibility problems between extensions and different skins, especially non-Vector skins - find what you should be doing and do it. If an external component is not doing what it should be doing, so you can't properly support it, fix it there. It will work out better in the long run than just adding a specific workaround.
• When creating a new interface intended for wider adoption, such as ones going through the RFC process, ensure that it will support this wider adoption, regardless of your specific reasons for having it added. Yes, your grant funding only specifically covers blah, but if your implementation of the core interface supports blah, blah, and blah fully as described by the RFC, the interface is much less likely to have its entire maintenance burden fall solely on you (or worse, have the entire thing get deprecated for lack of use or applicability), and you will likely still save money in the long run.

Endorsements

• Spreading your good engineering efforts and paying down technical debt beyond the boundaries of your specific project is good for everyone! Trey Jones (WMF) (talk) 15:48, 3 September 2019 (UTC)

See also

• ...

Related patterns

• Writing a new MediaWiki extension for deployment on a Wikimedia project
• Estimating time and complexity