Talk:Architecture:MediaWiki/Technical layers

The proposal as of the time I'm writing this comment has 12 layers. That feels like too many. I'm concerned that absorbing and applying the knowledge of what layer a piece of code should exist in will be intimidating to newer developers. I'm also concerned that it will be a source of less-than-productive debate for experienced/opinionated developers.

Intuitively, 5-7 layers feels like the correct amount.

I am intentionally not suggesting which layers should be combined or what the new set of layers should be, because I don't think it is relevant. Yes, clearly we would have to determine that if we adjust the proposal. But my focus in this comment is strictly on my concern that the average human would have significantly more difficulty categorizing things into 12 buckets than 5-7, based on https://en.wikipedia.org/wiki/The_Magical_Number_Seven,_Plus_or_Minus_Two .

And yes, I realize the article I just linked allows up to 9 things. But given the overall complexity of MediaWiki, a person already has a lot crammed into their brain while doing any significant development on it. So I feel we should err on the lower side of that range.

Right, I fear this is a result of me trying to be overly neat... Some layers could be combined, others are not "proper" layers. It would probably best to focus on the ones that are most relevant for most code. Perhaps something like this:

• (surface layer)
• user interface layer
• API layer
• behavior layer
• processing layer
• storage layer
• entity layer
• (foundation layer)

That's six real layers, plus two for "stuff above" and "stuff below". How does that sound?

If this is still too much, processing could be folded into storage. Structurally, that wouldn't be too terrible, though I'd like a better name, then.

We could also combine API and UI into an integration layer, but we'd lose a restriction I find important: the API shouldn't know about UI concepts and flows, it shouldn't care about i18n. Unless we are talking about a backend-for-frontend API, which would probably live in the UI layer...

This looks much better to me at a glance. There's probably room for discussion about whether or not this is exactly the right set of layers. But this seems like a good starting point for that discussion.

As I understand the proposal, code in "higher" layers can call code in "lower" layers. But the reverse is not allowed, If a class/function/etc. is determined to be miscategorized and is moved from a lower layer to a higher layer, some code that previously called it may no longer be able to.

Does this introduce a maintenance/deprecation situation that we should (a) be aware of and (b) create policies around.

Clearly, the best answer is "don't get it wrong in the first place", but ... stuff happens.

Also, this highlights the need for tooling around layers. It would be easy to miss some callers when refactoring after moving code between layers. Without tooling to help us catch the mistake, the code will happily continue to execute and it might be some time before the violation is noticed.

Yes, you are right, we need a tool to generate reports before we can truly establish layers. This tool could work something like this:

Group all classes by their layer (according to the @layer annotation). Classes without such an annotation go into a special "unknown" group, which is allowed to access most layers. Count "bad" dependencies for each group. For a given patch, the size of the "unknown" group should not grow, and the total number of "bad" dependencies should not grow. To allow us to incrementally introduce annotations, it's ok for the number of "bad" relationships to grow if the size of the Unknown group goes down at the same time.

This analysis should be integrated with CI. It should of course only start voting and blocking patches once we have annotated a good portion of the code.

This should not be hard to do, a simple version sounds like a nice weekend project. But we need to survey which software we want to build on and what we want to integrate with.

It's a bit of a chicken and egg problem, though. If we don't have agreement that we want to establish layers, there is no point in spending time on the tooling. But without the tooling, it's hard to establish a layer system.

As to deprecation: it would be very useful if we could ignore dependencies caused by deprecated code. I have not seen any analysis tool that does this, but I have talked to the maintainer of one such tool, and they seem open to adding it: https://github.com/mihaeu/dephpend/issues/42