Page MenuHomePhabricator

Replace docs/design.txt with a reasonably complete summary of how MW works
Open, LowPublic

Description

docs/design.txt is old and not very useful, but is probably frequently skimmed by new developers. Let's make it useful.

https://www.mediawiki.org/wiki/Architecture_guidelines is what we should want people to read. That document should be taken with the same level of seriousness that https://www.mediawiki.org/wiki/Security_for_developers gets. Let's actually make a piece of it part of our source tree, and point to https://www.mediawiki.org/wiki/Architecture_guidelines from docs/design.txt

Event Timeline

RobLa-WMF raised the priority of this task from to Needs Triage.
RobLa-WMF updated the task description. (Show Details)
RobLa-WMF added a subscriber: RobLa-WMF.
Restricted Application added a subscriber: Aklapper. · View Herald TranscriptSep 2 2015, 11:14 PM

Sounds good.

doxgen turns this into garbled https://doc.wikimedia.org/mediawiki-core/master/php/design_8txt.html , aggh. I created T111298: make doc files in git more useful but it's deliberately not a blocker of this.

Just make design.txt a pointer to the wiki page?

demon updated the task description. (Show Details)Sep 3 2015, 5:48 AM
demon set Security to None.

Just make design.txt a pointer to the wiki page?

No. We need to make it so that:

  • People looking for something using code search tools (e.g. grep) to find an important architectural concept (maybe hoping to find something in the comments) actually find this document
  • At least some of our design is actually documented in the code, and that we're not breathing so much of our own exhaust that we think everything can most comfortably be used on a wiki
  • The thing we're pointing to is actually worth reading, and doesn't have "draft" on the top of it after ... how many years?
  • Changes to the core document are treated seriously in code review, and use our code development process for its development
kchapman assigned this task to Krinkle.Sep 25 2018, 11:32 PM
kchapman moved this task from Inbox to Backlog on the TechCom board.
Krinkle triaged this task as Low priority.Oct 11 2018, 1:21 AM

Change 467138 had a related patch set uploaded (by Krinkle; owner: MGChecker):
[mediawiki/core@master] docs: Remove outdated information from globals.txt

https://gerrit.wikimedia.org/r/467138

Change 467138 merged by jenkins-bot:
[mediawiki/core@master] docs: Remove outdated information from globals.txt

https://gerrit.wikimedia.org/r/467138

Krinkle removed Krinkle as the assignee of this task.Feb 17 2019, 1:10 AM
Krinkle renamed this task from Replace docs/design.txt with a reasonably complete summary of mw:Architectural_guidelines to Replace docs/design.txt with a reasonably complete summary of how MW works.Feb 20 2019, 9:54 PM
Krinkle updated the task description. (Show Details)
Milimetric added a subscriber: Milimetric.

No clear owner any more.