Page MenuHomePhabricator

Provide a canonical place to document configuration variables of MobileFrontend
Closed, ResolvedPublic2 Story Points

Description

Right now there are two documentation pieces about the configuration variables on MobileFrontend and they are out of sync (which is normal and was bound to happen).

Let's agree on a single source of truth for documentation, either the README of the extension in the repository or the mediawiki.org/wiki/Extension:MobileFrontend and link from one place to the other.

My proposal would be to make the documentation on the repo the canonical place to check the configuration variables given it is versioned with the code, so given a version of the repository it is easy to see the documentation of the configuration that applies to that version.

If so then:

  • Sync mw.org config docs with the README.md (for example the wiki has $wgMinervaAlwaysShowLanguageButton but not the README)
  • Remove the configuration table from mw.org, link to the configuration portion of the README in the wiki (to diffussion and github)
  • Make a nice markdown format for the configuration variables, like the table, but in markdown so that it is easier to read.
    • Improved formatting, not table bc of code syntax

See https://github.com/wikimedia/mediawiki-extensions-MobileFrontend/blob/master/README.md

Event Timeline

Restricted Application added subscribers: Zppix, Aklapper. · View Herald TranscriptJul 18 2016, 11:15 AM
Jhernandez triaged this task as High priority.Jul 18 2016, 11:15 AM
Jhernandez added a project: good first bug.
Jhernandez moved this task from Incoming to Triaged but Future on the Readers-Web-Backlog board.
Restricted Application added a subscriber: TerraCodes. · View Herald TranscriptJul 18 2016, 11:15 AM
Jhernandez updated the task description. (Show Details)Jul 18 2016, 11:17 AM
Jhernandez added a subscriber: Jdlrobson.

@Jdlrobson I've come across some inconsistencies when signing off the config change on wikibase descriptions, so I think we should get this done sooner than later.

Do you agree with making the docs in the README the canonical ones for configuration variables? (given they are in sync with the actual code?)

I agree. In an attempt at being bold I've linked to the README from the MediaWiki page:
https://www.mediawiki.org/w/index.php?title=Extension%3AMobileFrontend&type=revision&diff=2194265&oldid=2192903

I'll submit some patches for the README.

Change 299773 had a related patch set uploaded (by Jdlrobson):
Update README.md to document undocumented variables

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

Jdlrobson updated the task description. (Show Details)Jul 19 2016, 4:04 PM

Change 299773 merged by jenkins-bot:
Update README.md to document undocumented variables

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

Jdlrobson updated the task description. (Show Details)

Change 299807 had a related patch set uploaded (by Jhernandez):
Improve formatting and fix markdown errors in README

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

Change 299808 had a related patch set uploaded (by Jhernandez):
Consistently wrap README at 80 and linkify URLS

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

Change 299810 had a related patch set uploaded (by Jhernandez):
Fix Configuration section (duplicated) in README

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

Change 299811 had a related patch set uploaded (by Jhernandez):
Remove outdated release process information (readme)

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

@Jdlrobson I've spent some time formatting the readme and making it more consistent/well formatted.

I've also updated the (link to mw)config and release sections (removed bc outdated)

Review plz if you have a moment. Formatting is/was all broken, see https://phabricator.wikimedia.org/diffusion/EMFR/#configuration-options for example

This should improve it a lot.

Change 299807 merged by jenkins-bot:
Improve formatting and fix markdown errors in README

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

Change 299808 merged by jenkins-bot:
Consistently wrap README at 80 and linkify URLS

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

Change 299810 merged by jenkins-bot:
Fix Configuration section (duplicated) in README

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

Jenkins got stuck in the last one. Rechecking and I'll sign off as it's done

Change 299811 merged by jenkins-bot:
Remove outdated release process information (readme)

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

Jhernandez closed this task as Resolved.Jul 20 2016, 1:37 PM
Jhernandez claimed this task.
Jhernandez updated the task description. (Show Details)

All merged and fixed, signing off

Jhernandez set the point value for this task to 2.Jul 20 2016, 1:38 PM

@Jdlrobson I've estimated a 2 for this. If you feel differently feel free to change it.

Jdlrobson reopened this task as Open.Jul 20 2016, 6:52 PM

There are still undocumented variables in extension.json

Change 300079 had a related patch set uploaded (by Jdlrobson):
The README.md is the canonical place for documentation of config vars

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

Jhernandez closed this task as Resolved.Jul 21 2016, 12:03 PM

Nice! I've merged

Change 300079 merged by jenkins-bot:
The README.md is the canonical place for documentation of config vars

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