Page MenuHomePhabricator

BoilerPlate extension should show latest coding practices
Open, LowPublic

Description

Besides linters and entry points (T94275), we should put other best practices in BoilerPlate:

  • additional continuous integration:
  • documentation generation: doxygen, jsduck, KSS documentation
    • PD extension help (example), using getOutput->addHelpLink() ?
  • tests: browser tests, phpunit, qunit
  • new MediaWiki features and practices
    • extension.json
    • PSR logging
    • Config interface (getConfig()->get( 'CategoryPagingLimit') instead of $wgCategoryPagingLimit)
    • assert handling

The last set raises the question of whether BoilerPlate master should use only cutting-edge features or demonstrate backwards compatibility with the latest release or LTS release.

Event Timeline

Spage raised the priority of this task from to Medium.
Spage updated the task description. (Show Details)
Spage added a subscriber: Spage.
Spage set Security to None.

Maybe we need a needs-example-code tag similar to the documentation tag that would remind a feature's developer to update BoilerPlate.

BoilerPlate should have no source code comments on features -- it's a skeleton, not tutorial documentation. Instead developers using BoilerPlate can use git log and git blame to find rationale for any line of code. This means BoilerPlate changes must have sensational commit messages mentioning the related feature commit, any RFC, phab task, etc.

If a developer bases an extension off BoilerPlate, how can she incorporate later updates to BoilerPlate?

Maybe we need a needs-example-code tag similar to the documentation tag that would remind a feature's developer to update BoilerPlate.

It's an interesting idea. Please create a task to request this tag, and we can discuss it there.

BoilerPlate should have no source code comments on features -- it's a skeleton, not tutorial documentation.

Mmm... are you sure about this? What is the problem with a self-explanatory verbose skeleton? Keeping a file in a source code repository in sync with a wiki page would serve a double purpose of theoretical/practical training efficiently, I believe. When you use such skeletons for actually developing a new product, it is normal to go through the code and remove/comment what you won't need.

I mean, you don't need to offer the whole manual there, but it could be useful to have basic comments including URLs where such aspect is explained at length.

I think this is worth attempting in June (now July). If we can reorg git repos to make Blueprint a top-level extension it'll make integration easier.

Qgil lowered the priority of this task from Medium to Low.Aug 8 2015, 12:53 PM

Low, as discussed.

Change 371077 had a related patch set uploaded (by Samwilson; owner: Samwilson):
[mediawiki/extensions/BoilerPlate@master] Add new-style configuration values with prefix

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

Change 371077 merged by jenkins-bot:
[mediawiki/extensions/BoilerPlate@master] Add new-style configuration values with prefix

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

The patch I submitted above is not actually correct; it should not use config_prefix etc. (I'm fixing it now; just noting this here in case I don't.)

Change 383302 had a related patch set uploaded (by Samwilson; owner: Samwilson):
[mediawiki/extensions/BoilerPlate@master] Move classes into src directory, and remove exclusions for phpcs

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

Change 383302 merged by jenkins-bot:
[mediawiki/extensions/BoilerPlate@master] Move classes into src directory, and remove exclusions for phpcs

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

Change 534615 had a related patch set uploaded (by Kosta Harlan; owner: Kosta Harlan):
[mediawiki/extensions/BoilerPlate@master] Add unit test example

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

Change 534615 merged by jenkins-bot:
[mediawiki/extensions/BoilerPlate@master] Add unit test example

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